@nsxbet/admin-sdk 0.1.0

package/README.md

@@ -0,0 +1,680 @@
+# @nsxbet/admin-sdk
+
+SDK for building admin modules for the NSX Admin platform.
+
+## Installation
+
+```bash
+bun add @nsxbet/admin-sdk @nsxbet/admin-ui
+```
+
+**Peer dependencies** (install these too):
+
+```bash
+bun add react react-dom react-router-dom i18next react-i18next
+bun add -D @vitejs/plugin-react vite tailwindcss postcss autoprefixer typescript
+```
+
+## Quick Start
+
+This SDK enables you to build admin modules that integrate with the NSX Admin shell. Modules are loaded dynamically via React.lazy and share the shell's Router context.
+
+**Key concepts:**
+- Modules export a default React component from `spa.tsx`
+- Modules share the shell's `BrowserRouter` - use `useNavigate()` from `react-router-dom` directly
+- Use `@nsxbet/admin-ui` for consistent UI components
+- Define module metadata in `admin.module.json`
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Shell (BrowserRouter)                                          │
+│  ├── TopBar, LeftNav, CommandPalette                           │
+│  └── <Route path="/your-module/*">                             │
+│       └── React.lazy(() => import(baseUrl/spa.js))             │
+│            └── Your App component (shares Router context)       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Two entry points pattern:**
+
+| File | Purpose | When used |
+|------|---------|-----------|
+| `src/spa.tsx` | Default export of App | Shell loads this via React.lazy |
+| `src/standalone.tsx` | Full app with AdminShell wrapper | Local development (`npm run dev`) |
+
+## Complete Module Example
+
+Below are all the files needed for a working module. Copy these and modify for your needs.
+
+### File: `vite.config.ts`
+
+```typescript
+import { defineModuleConfig } from "@nsxbet/admin-sdk/vite";
+import react from "@vitejs/plugin-react";
+
+export default defineModuleConfig({
+  port: 3003,
+  plugins: [react()],
+});
+```
+
+### File: `admin.module.json`
+
+```json
+{
+  "id": "@admin/my-module",
+  "title": "My Module",
+  "description": "Description of what this module does",
+  "version": "1.0.0",
+  "category": "Tools",
+  "icon": "clipboard-list",
+  "routeBase": "/my-module",
+  "keywords": ["my", "module", "example"],
+  "commands": [
+    {
+      "id": "list",
+      "title": "List Items",
+      "route": "/my-module/list",
+      "icon": "file-text"
+    },
+    {
+      "id": "new",
+      "title": "New Item",
+      "route": "/my-module/new",
+      "icon": "plus"
+    }
+  ],
+  "permissions": {
+    "view": ["admin.mymodule.view"],
+    "edit": ["admin.mymodule.edit"],
+    "delete": ["admin.mymodule.delete"]
+  },
+  "owners": {
+    "team": "Platform",
+    "supportChannel": "#platform-support"
+  }
+}
+```
+
+### File: `src/spa.tsx`
+
+```tsx
+/**
+ * Module entry point for shell mode.
+ * The module shares the shell's Router context.
+ */
+import { App } from "./App";
+
+export default App;
+```
+
+### File: `src/standalone.tsx`
+
+```tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { AdminShell, initI18n, i18n } from "@nsxbet/admin-sdk";
+import type { AdminModuleManifest } from "@nsxbet/admin-sdk";
+import { App } from "./App";
+import manifest from "../admin.module.json";
+
+import "./index.css";
+
+// Import module translations (optional - for i18n support)
+import enUS from "./i18n/locales/en-US.json";
+import ptBR from "./i18n/locales/pt-BR.json";
+
+// Initialize i18n BEFORE shell renders
+initI18n();
+
+// Register module translations with namespace matching your module
+const NAMESPACE = "mymodule";
+i18n.addResourceBundle("en-US", NAMESPACE, enUS, true, true);
+i18n.addResourceBundle("pt-BR", NAMESPACE, ptBR, true, true);
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <AdminShell modules={[manifest as AdminModuleManifest]}>
+      <App />
+    </AdminShell>
+  </React.StrictMode>
+);
+```
+
+### File: `src/App.tsx`
+
+```tsx
+import { Routes, Route, Navigate } from "react-router-dom";
+import { ItemList } from "./ItemList";
+import { NewItem } from "./NewItem";
+
+export function App() {
+  return (
+    <Routes>
+      {/* Redirect root to list */}
+      <Route path="/" element={<Navigate to="list" replace />} />
+      <Route path="list" element={<ItemList />} />
+      <Route path="new" element={<NewItem />} />
+    </Routes>
+  );
+}
+```
+
+### File: `src/ItemList.tsx`
+
+```tsx
+import { useEffect } from "react";
+import { useNavigate } from "react-router-dom";
+import { useAuth, usePlatformAPI, useTelemetry } from "@nsxbet/admin-sdk";
+import { Button, Card, CardContent, Badge } from "@nsxbet/admin-ui";
+
+export function ItemList() {
+  const navigate = useNavigate();
+  const { hasPermission } = useAuth();
+  const { api } = usePlatformAPI();
+  const { track } = useTelemetry();
+
+  const canEdit = hasPermission("admin.mymodule.edit");
+
+  useEffect(() => {
+    // Set breadcrumbs
+    api?.nav.setBreadcrumbs([
+      { label: "My Module" },
+      { label: "List" }
+    ]);
+    // Track page view
+    track("page.viewed", { page: "item_list" });
+  }, [api, track]);
+
+  return (
+    <div className="p-6 max-w-5xl mx-auto">
+      <div className="mb-6 flex items-center justify-between">
+        <h1 className="text-3xl font-bold">Items</h1>
+        {canEdit && (
+          <Button onClick={() => navigate("/my-module/new")}>
+            New Item
+          </Button>
+        )}
+      </div>
+
+      <Card>
+        <CardContent className="p-4">
+          <p className="text-muted-foreground">No items yet.</p>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+
+### File: `src/index.css`
+
+```css
+@import "@nsxbet/admin-ui/styles.css";
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+### File: `tailwind.config.js`
+
+Use `withAdminSdk` which automatically includes the UI preset and SDK/UI content paths:
+
+```javascript
+import { withAdminSdk } from "@nsxbet/admin-sdk/tailwind";
+
+/** @type {import('tailwindcss').Config} */
+export default withAdminSdk({
+  content: ["./index.html", "./src/**/*.{ts,tsx}"],
+});
+```
+
+### File: `package.json`
+
+```json
+{
+  "name": "@admin/my-module",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build && cp admin.module.json dist/",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@nsxbet/admin-sdk": "latest",
+    "@nsxbet/admin-ui": "latest",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router-dom": "^6.20.0",
+    "i18next": "^25.0.0",
+    "react-i18next": "^16.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.2.0",
+    "autoprefixer": "^10.4.16",
+    "postcss": "^8.4.32",
+    "tailwindcss": "^3.4.0",
+    "typescript": "^5.2.0",
+    "vite": "^5.0.0"
+  }
+}
+```
+
+### File: `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src", "admin.module.json"]
+}
+```
+
+### File: `index.html`
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My Module - Standalone</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/standalone.tsx"></script>
+  </body>
+</html>
+```
+
+### File: `postcss.config.js`
+
+```javascript
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+```
+
+## Manifest Schema (`admin.module.json`)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | ✅ | Unique identifier (e.g., `@admin/tasks`) |
+| `title` | string | ✅ | Human-readable title |
+| `routeBase` | string | ✅ | Base route path (must start with `/`) |
+| `description` | string | | What the module does |
+| `version` | string | | Semantic version |
+| `category` | string | | Navigation grouping |
+| `icon` | string | | Lucide icon name in kebab-case |
+| `keywords` | string[] | | Search keywords |
+| `commands` | Command[] | | Available actions |
+| `permissions` | object | | Permission configuration |
+| `owners` | object | | Team ownership info |
+
+### Command Schema
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | ✅ | Unique command identifier |
+| `title` | string | ✅ | Command title |
+| `route` | string | ✅ | Full route path |
+| `icon` | string | | Lucide icon name |
+| `keywords` | string[] | | Search keywords |
+
+### Icon Names
+
+Use [Lucide](https://lucide.dev/icons) icon names in **kebab-case**:
+
+| Category | Icons |
+|----------|-------|
+| Navigation | `home`, `settings`, `menu`, `search`, `chevron-right` |
+| Actions | `plus`, `edit`, `trash`, `copy`, `check` |
+| Content | `file`, `file-text`, `folder`, `clipboard-list` |
+| Users | `user`, `users` |
+| Status | `alert-circle`, `info`, `ban`, `lock` |
+
+## Vite Configuration
+
+The SDK provides `defineModuleConfig` to simplify Vite setup:
+
+```typescript
+import { defineModuleConfig } from "@nsxbet/admin-sdk/vite";
+import react from "@vitejs/plugin-react";
+
+export default defineModuleConfig({
+  port: 3003,
+  plugins: [react()], // REQUIRED: you must add the React plugin
+});
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `port` | number | **required** | Dev server port |
+| `entry` | string | `"./src/spa.tsx"` | Entry file path |
+| `outDir` | string | `"dist"` | Output directory |
+| `plugins` | Plugin[] | `[]` | Additional Vite plugins |
+| `additionalExternals` | string[] | `[]` | Extra externals |
+| `overrides` | object | `{}` | Override any Vite config |
+
+### Shared Externals
+
+These dependencies are provided by the shell (do not bundle them):
+
+```typescript
+["react", "react-dom", "react-router-dom", "i18next", "react-i18next"]
+```
+
+## SDK Hooks
+
+### `useAuth()`
+
+Access authentication and permissions.
+
+```typescript
+import { useAuth } from "@nsxbet/admin-sdk";
+
+function MyComponent() {
+  const { hasPermission, getUser, getAccessToken, logout } = useAuth();
+
+  if (!hasPermission("admin.mymodule.view")) {
+    return <div>Access denied</div>;
+  }
+
+  const user = getUser();
+  console.log(user.email, user.displayName);
+}
+```
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `hasPermission(perm)` | boolean | Check if user has permission |
+| `getUser()` | User | Get current user info |
+| `getAccessToken()` | Promise\<string\> | Get JWT token |
+| `logout()` | void | Log out user |
+
+### `usePlatformAPI()`
+
+Access the shell's platform API.
+
+```typescript
+import { usePlatformAPI } from "@nsxbet/admin-sdk";
+
+function MyComponent() {
+  const { api, isShellMode } = usePlatformAPI();
+
+  useEffect(() => {
+    api?.nav.setBreadcrumbs([
+      { label: "My Module" },
+      { label: "Current Page" }
+    ]);
+  }, [api]);
+}
+```
+
+### `useFetch()`
+
+Make authenticated API requests.
+
+```typescript
+import { useFetch } from "@nsxbet/admin-sdk";
+
+function MyComponent() {
+  const fetch = useFetch();
+
+  const loadData = async () => {
+    const response = await fetch("/api/data");
+    const data = await response.json();
+  };
+}
+```
+
+### `useTelemetry()`
+
+Track events and errors.
+
+```typescript
+import { useTelemetry } from "@nsxbet/admin-sdk";
+
+function MyComponent() {
+  const { track, trackError } = useTelemetry();
+
+  const handleClick = () => {
+    track("button.clicked", { buttonId: "save" });
+  };
+
+  const handleError = (error: Error) => {
+    trackError(error, { context: "save_operation" });
+  };
+}
+```
+
+### `useI18n()`
+
+Manage translations and locale.
+
+```typescript
+import { useI18n } from "@nsxbet/admin-sdk";
+
+function MyComponent() {
+  const { t, locale, setLocale } = useI18n();
+
+  return (
+    <div>
+      <h1>{t("common.title")}</h1>
+      <p>Current locale: {locale}</p>
+    </div>
+  );
+}
+```
+
+### Navigation
+
+**Use `useNavigate` from `react-router-dom` directly:**
+
+```typescript
+import { useNavigate } from "react-router-dom";
+
+function MyComponent() {
+  const navigate = useNavigate();
+
+  return (
+    <Button onClick={() => navigate("/my-module/new")}>
+      New Item
+    </Button>
+  );
+}
+```
+
+## DO NOT (Common Mistakes)
+
+### ❌ DO NOT use MemoryRouter
+
+```tsx
+// WRONG - don't create your own router
+import { MemoryRouter, Routes, Route } from "react-router-dom";
+
+function App() {
+  return (
+    <MemoryRouter> {/* ❌ WRONG */}
+      <Routes>
+        <Route path="/" element={<List />} />
+      </Routes>
+    </MemoryRouter>
+  );
+}
+```
+
+```tsx
+// CORRECT - use Routes directly, shell provides BrowserRouter
+import { Routes, Route } from "react-router-dom";
+
+function App() {
+  return (
+    <Routes>
+      <Route path="/" element={<List />} />
+    </Routes>
+  );
+}
+```
+
+### ❌ DO NOT create BrowserRouter in spa.tsx
+
+```tsx
+// WRONG - shell already provides BrowserRouter
+import { BrowserRouter } from "react-router-dom";
+
+export default function App() {
+  return (
+    <BrowserRouter> {/* ❌ WRONG */}
+      <MyRoutes />
+    </BrowserRouter>
+  );
+}
+```
+
+```tsx
+// CORRECT - just export the component
+import { App } from "./App";
+export default App;
+```
+
+### ❌ DO NOT forget the React plugin
+
+```typescript
+// WRONG - missing React plugin
+export default defineModuleConfig({
+  port: 3003,
+  // ❌ No plugins!
+});
+```
+
+```typescript
+// CORRECT - include React plugin
+import react from "@vitejs/plugin-react";
+
+export default defineModuleConfig({
+  port: 3003,
+  plugins: [react()], // ✅
+});
+```
+
+### ❌ DO NOT use external databases
+
+```typescript
+// WRONG - no Supabase, Firebase, or external BaaS
+import { createClient } from "@supabase/supabase-js"; // ❌
+import { initializeApp } from "firebase/app"; // ❌
+```
+
+```typescript
+// CORRECT - use authenticated fetch for internal APIs
+import { useFetch } from "@nsxbet/admin-sdk";
+
+const fetch = useFetch();
+const data = await fetch("/api/internal-endpoint");
+```
+
+### ❌ DO NOT import useNavigate from SDK
+
+```typescript
+// WRONG - useNavigate is not exported from SDK
+import { useNavigate } from "@nsxbet/admin-sdk"; // ❌
+```
+
+```typescript
+// CORRECT - import from react-router-dom
+import { useNavigate } from "react-router-dom"; // ✅
+```
+
+## Troubleshooting
+
+### "Failed to resolve module specifier 'react'"
+
+**Cause:** Module is bundling React instead of using shell's version.
+
+**Solution:** Ensure `vite.config.ts` uses `defineModuleConfig` or has `external: ["react", "react-dom", "react-router-dom"]`.
+
+### "process is not defined"
+
+**Cause:** Module code references Node.js globals.
+
+**Solution:** `defineModuleConfig` handles this automatically. If using custom config, add:
+
+```typescript
+define: {
+  "process.env": {},
+  "process.env.NODE_ENV": JSON.stringify("production"),
+}
+```
+
+### Module not loading in shell
+
+**Checklist:**
+1. ✅ `spa.tsx` exports default component
+2. ✅ `admin.module.json` has valid `id`, `title`, `routeBase`
+3. ✅ Build outputs to `dist/` with `spa-[hash].js`
+4. ✅ Module is registered in shell's catalog
+
+### Styles not working
+
+**Checklist:**
+1. ✅ `index.css` imports `@nsxbet/admin-ui/styles.css`
+2. ✅ `tailwind.config.js` uses `withAdminSdk` from `@nsxbet/admin-sdk/tailwind`
+3. ✅ `postcss.config.js` exists with tailwindcss plugin
+
+## Running Your Module
+
+```bash
+# Development (standalone with shell UI)
+bun run dev
+# Open http://localhost:3003
+
+# Build for production
+bun run build
+# Output: dist/assets/spa-[hash].js
+
+# Preview built module
+bun run preview
+```
+
+## Types
+
+```typescript
+import type {
+  AdminModuleManifest,
+  ModuleCommand,
+  PlatformAPI,
+  User,
+  Breadcrumb,
+} from "@nsxbet/admin-sdk";
+```
+
+## License
+
+UNLICENSED - Internal use only

package/dist/auth/client/in-memory.d.ts

@@ -0,0 +1,27 @@
+/**
+ * In-Memory Auth Client
+ *
+ * Provides fake authentication for development and testing.
+ * Users can be selected from a predefined list or created custom.
+ */
+import type { MockUser, InMemoryAuthClient } from './interface';
+/**
+ * Options for creating an in-memory auth client
+ */
+export interface InMemoryAuthClientOptions {
+    /** Custom mock users (merged with defaults) */
+    users?: MockUser[];
+    /** Replace default users instead of merging */
+    replaceDefaults?: boolean;
+    /** localStorage key prefix (defaults to '@nsxbet/auth') */
+    storageKey?: string;
+}
+/**
+ * Create an in-memory auth client for development/testing
+ */
+export declare function createInMemoryAuthClient(options?: InMemoryAuthClientOptions): InMemoryAuthClient;
+/**
+ * Clear in-memory auth storage (useful for tests)
+ */
+export declare function clearInMemoryAuth(storageKey?: string): void;
+//# sourceMappingURL=in-memory.d.ts.map

package/dist/auth/client/in-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory.d.ts","sourceRoot":"","sources":["../../../src/auth/client/in-memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAgC,MAAM,aAAa,CAAC;AAoD9F;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,+CAA+C;IAC/C,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAYD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,yBAA8B,GAAG,kBAAkB,CAiNpG;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,SAAsB,GAAG,IAAI,CAExE"}