@ulfblk/admin 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# @ulfblk/admin
+
+React Admin DataProvider and AuthProvider for the ulfblk ecosystem.
+
+## Installation
+
+```bash
+pnpm add @ulfblk/admin react-admin
+```
+
+## Quick Start
+
+```tsx
+import { Admin, Resource, ListGuesser, EditGuesser } from "react-admin";
+import { BloqueClient } from "@ulfblk/api-client";
+import { createDataProvider, createAuthProvider } from "@ulfblk/admin";
+
+const client = new BloqueClient({ baseUrl: "http://localhost:8000" });
+const dataProvider = createDataProvider(client);
+const authProvider = createAuthProvider(client);
+
+function App() {
+  return (
+    <Admin dataProvider={dataProvider} authProvider={authProvider}>
+      <Resource name="users" list={ListGuesser} edit={EditGuesser} />
+      <Resource name="orders" list={ListGuesser} edit={EditGuesser} />
+    </Admin>
+  );
+}
+```
+
+## Features
+
+- **DataProvider**: CRUD operations via BloqueClient with FastAPI-compatible query serialization (`qs` with `arrayFormat: 'repeat'`)
+- **AuthProvider**: JWT login/logout with client-side token validation via `jwt-decode`
+- **Tenant-aware**: BloqueClient's tenant interceptor handles tenant context automatically
+- **Configurable**: Custom `basePath`, query serializer, login path
+- **Error handling**: Maps HTTP errors to react-admin's `HttpError` (401 -> re-login, 403 -> access denied)
+- **Batch operations**: `deleteMany`/`updateMany` execute in batches of 5 to avoid overwhelming the backend
+
+## Options
+
+```tsx
+// Custom base path
+const dataProvider = createDataProvider(client, { basePath: "/v1" });
+
+// Custom login endpoint
+const authProvider = createAuthProvider(client, { loginPath: "/auth/login" });
+
+// Multi-tenant: switch tenants dynamically
+client.setTenantId("acme");
+// All subsequent requests include tenant context via interceptor
+```
+
+## Backend Requirements
+
+The DataProvider expects standard REST endpoints:
+
+| Method | Endpoint | react-admin method |
+|--------|----------|-------------------|
+| GET | `{basePath}/{resource}` | getList, getMany |
+| GET | `{basePath}/{resource}/{id}` | getOne |
+| POST | `{basePath}/{resource}` | create |
+| PUT | `{basePath}/{resource}/{id}` | update |
+| DELETE | `{basePath}/{resource}/{id}` | delete |
+
+List responses must match `PaginatedResponse`:
+```json
+{ "items": [...], "total": 100 }
+```

package/dist/auth-provider.d.ts

@@ -0,0 +1,10 @@
+/**
+ * React Admin AuthProvider using BloqueClient.
+ *
+ * Handles login/logout, token validation via jwt-decode,
+ * and permission extraction from JWT payload.
+ */
+import type { AuthProvider } from "react-admin";
+import type { BloqueClient } from "@ulfblk/api-client";
+import type { AuthProviderOptions } from "./types.js";
+export declare function createAuthProvider(client: BloqueClient, options?: AuthProviderOptions): AuthProvider;

package/dist/auth-provider.js

@@ -0,0 +1,81 @@
+/**
+ * React Admin AuthProvider using BloqueClient.
+ *
+ * Handles login/logout, token validation via jwt-decode,
+ * and permission extraction from JWT payload.
+ */
+import { jwtDecode } from "jwt-decode";
+function isTokenExpired(token) {
+    try {
+        const decoded = jwtDecode(token);
+        return decoded.exp * 1000 < Date.now();
+    }
+    catch {
+        return true;
+    }
+}
+function getPayload(token) {
+    try {
+        return jwtDecode(token);
+    }
+    catch {
+        return null;
+    }
+}
+export function createAuthProvider(client, options) {
+    const loginPath = options?.loginPath ?? "/auth/login";
+    let lastToken = null;
+    return {
+        login: async ({ username, password }) => {
+            const response = await client.post(loginPath, { email: username, password });
+            client.setTokens({
+                accessToken: response.access_token,
+                refreshToken: response.refresh_token,
+            });
+            lastToken = response.access_token;
+        },
+        logout: async () => {
+            client.logout();
+            lastToken = null;
+        },
+        checkAuth: async () => {
+            if (!lastToken || isTokenExpired(lastToken)) {
+                throw new Error("Token expired or missing");
+            }
+        },
+        checkError: async (error) => {
+            if (error.status === 401) {
+                client.logout();
+                lastToken = null;
+                throw new Error("Unauthorized");
+            }
+            // 403 = valid token but no permission - don't logout
+            if (error.status === 403) {
+                throw new Error("Forbidden");
+            }
+        },
+        getPermissions: async () => {
+            if (!lastToken)
+                return { roles: [], permissions: [] };
+            const payload = getPayload(lastToken);
+            if (!payload)
+                return { roles: [], permissions: [] };
+            return {
+                roles: payload.roles ?? [],
+                permissions: payload.permissions ?? [],
+            };
+        },
+        getIdentity: async () => {
+            if (!lastToken)
+                throw new Error("Not authenticated");
+            const payload = getPayload(lastToken);
+            if (!payload)
+                throw new Error("Invalid token");
+            return {
+                id: payload.sub,
+                fullName: payload.sub,
+                tenant: payload.tenant,
+            };
+        },
+    };
+}

package/dist/data-provider.d.ts

@@ -0,0 +1,13 @@
+/**
+ * React Admin DataProvider using BloqueClient as HTTP transport.
+ *
+ * Translates react-admin CRUD calls to REST endpoints.
+ * Uses `qs` for query string serialization (FastAPI-compatible).
+ *
+ * Tenant context is handled automatically via BloqueClient's
+ * tenant interceptor (call client.setTenantId() to switch tenants).
+ */
+import type { DataProvider } from "react-admin";
+import type { BloqueClient } from "@ulfblk/api-client";
+import type { DataProviderOptions } from "./types.js";
+export declare function createDataProvider(client: BloqueClient, options?: DataProviderOptions): DataProvider;

package/dist/data-provider.js

@@ -0,0 +1,110 @@
+/**
+ * React Admin DataProvider using BloqueClient as HTTP transport.
+ *
+ * Translates react-admin CRUD calls to REST endpoints.
+ * Uses `qs` for query string serialization (FastAPI-compatible).
+ *
+ * Tenant context is handled automatically via BloqueClient's
+ * tenant interceptor (call client.setTenantId() to switch tenants).
+ */
+import { HttpError } from "react-admin";
+import { stringify } from "qs";
+const BATCH_SIZE = 5;
+function defaultSerializer(params) {
+    return stringify(params, { arrayFormat: "repeat", skipNulls: true });
+}
+async function batchExecute(ids, fn) {
+    const results = [];
+    for (let i = 0; i < ids.length; i += BATCH_SIZE) {
+        const batch = ids.slice(i, i + BATCH_SIZE);
+        const batchResults = await Promise.all(batch.map(fn));
+        results.push(...batchResults);
+    }
+    return results;
+}
+export function createDataProvider(client, options) {
+    const base = (options?.basePath ?? "/api").replace(/\/+$/, "");
+    const serialize = options?.querySerializer ?? defaultSerializer;
+    async function request(method, path, body) {
+        try {
+            switch (method) {
+                case "GET":
+                    return await client.get(path);
+                case "POST":
+                    return await client.post(path, body);
+                case "PUT":
+                    return await client.put(path, body);
+                case "DELETE":
+                    return await client.delete(path);
+                default:
+                    throw new Error(`Unsupported method: ${method}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && "status" in error) {
+                const e = error;
+                throw new HttpError(e.message, e.status, e.body);
+            }
+            throw error;
+        }
+    }
+    return {
+        getList: async (resource, params) => {
+            const { page, perPage } = params.pagination ?? { page: 1, perPage: 20 };
+            const { field, order } = params.sort ?? { field: "id", order: "ASC" };
+            const query = serialize({
+                page,
+                size: perPage,
+                sort: field,
+                order,
+                ...params.filter,
+            });
+            const url = `${base}/${resource}?${query}`;
+            const response = await request("GET", url);
+            return { data: response.items, total: response.total };
+        },
+        getOne: async (resource, params) => {
+            const data = await request("GET", `${base}/${resource}/${params.id}`);
+            return { data };
+        },
+        getMany: async (resource, params) => {
+            const query = serialize({ id: params.ids });
+            const response = await request("GET", `${base}/${resource}?${query}`);
+            return { data: response.items };
+        },
+        getManyReference: async (resource, params) => {
+            const { page, perPage } = params.pagination ?? { page: 1, perPage: 20 };
+            const { field, order } = params.sort ?? { field: "id", order: "ASC" };
+            const query = serialize({
+                page,
+                size: perPage,
+                sort: field,
+                order,
+                [params.target]: params.id,
+                ...params.filter,
+            });
+            const response = await request("GET", `${base}/${resource}?${query}`);
+            return { data: response.items, total: response.total };
+        },
+        create: async (resource, params) => {
+            const data = await request("POST", `${base}/${resource}`, params.data);
+            return { data };
+        },
+        update: async (resource, params) => {
+            const data = await request("PUT", `${base}/${resource}/${params.id}`, params.data);
+            return { data };
+        },
+        delete: async (resource, params) => {
+            const data = await request("DELETE", `${base}/${resource}/${params.id}`);
+            return { data };
+        },
+        deleteMany: async (resource, params) => {
+            await batchExecute(params.ids, (id) => request("DELETE", `${base}/${resource}/${id}`));
+            return { data: params.ids };
+        },
+        updateMany: async (resource, params) => {
+            await batchExecute(params.ids, (id) => request("PUT", `${base}/${resource}/${id}`, params.data));
+            return { data: params.ids };
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @ulfblk/admin - React Admin providers for the ulfblk ecosystem.
+ *
+ * Provides DataProvider and AuthProvider that use BloqueClient
+ * as the HTTP transport layer, with automatic tenant context,
+ * JWT auth, and FastAPI-compatible query serialization.
+ */
+export { createDataProvider } from "./data-provider.js";
+export { createAuthProvider } from "./auth-provider.js";
+export type { DataProviderOptions, AuthProviderOptions, ListResponse } from "./types.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @ulfblk/admin - React Admin providers for the ulfblk ecosystem.
+ *
+ * Provides DataProvider and AuthProvider that use BloqueClient
+ * as the HTTP transport layer, with automatic tenant context,
+ * JWT auth, and FastAPI-compatible query serialization.
+ */
+export { createDataProvider } from "./data-provider.js";
+export { createAuthProvider } from "./auth-provider.js";

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Configuration options for the ulfblk DataProvider.
+ */
+export interface DataProviderOptions {
+    /** Base path for API endpoints. Default: "/api" */
+    basePath?: string;
+    /**
+     * Custom query string serializer.
+     * Default uses `qs` with arrayFormat: 'repeat' (FastAPI-compatible).
+     */
+    querySerializer?: (params: Record<string, unknown>) => string;
+}
+/**
+ * Configuration options for the ulfblk AuthProvider.
+ */
+export interface AuthProviderOptions {
+    /** Path for the login endpoint. Default: "/auth/login" */
+    loginPath?: string;
+}
+/**
+ * Expected response format from list endpoints.
+ * Must match PaginatedResponse from the Python backend.
+ */
+export interface ListResponse<T = Record<string, unknown>> {
+    items: T[];
+    total: number;
+    page?: number;
+    page_size?: number;
+    pages?: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ulfblk/admin",
+  "version": "0.1.0",
+  "description": "React Admin DataProvider and AuthProvider for the ulfblk ecosystem",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abelardodiaz/web25-991-bloques-reciclables",
+    "directory": "packages/typescript/ulfblk-admin"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "lint": "biome check src/",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@ulfblk/api-client": "^0.1.0",
+    "@ulfblk/types": "^0.1.0",
+    "qs": "^6.14.0"
+  },
+  "devDependencies": {
+    "@types/qs": "^6.9.0",
+    "jwt-decode": "^4.0.0",
+    "react-admin": "^5.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "react-admin": "^5.0.0",
+    "react": "^18 || ^19"
+  },
+  "peerDependenciesMeta": {
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "keywords": ["react-admin", "admin", "data-provider", "auth-provider", "ulfblk", "saas"]
+}

package/src/auth-provider.ts

@@ -0,0 +1,103 @@
+/**
+ * React Admin AuthProvider using BloqueClient.
+ *
+ * Handles login/logout, token validation via jwt-decode,
+ * and permission extraction from JWT payload.
+ */
+
+import type { AuthProvider } from "react-admin";
+import type { BloqueClient } from "@ulfblk/api-client";
+import { jwtDecode } from "jwt-decode";
+import type { AuthProviderOptions } from "./types.js";
+
+interface JwtPayload {
+  sub: string;
+  tenant: string;
+  exp: number;
+  type: string;
+  roles?: string[];
+  permissions?: string[];
+}
+
+function isTokenExpired(token: string): boolean {
+  try {
+    const decoded = jwtDecode<JwtPayload>(token);
+    return decoded.exp * 1000 < Date.now();
+  } catch {
+    return true;
+  }
+}
+
+function getPayload(token: string): JwtPayload | null {
+  try {
+    return jwtDecode<JwtPayload>(token);
+  } catch {
+    return null;
+  }
+}
+
+export function createAuthProvider(
+  client: BloqueClient,
+  options?: AuthProviderOptions,
+): AuthProvider {
+  const loginPath = options?.loginPath ?? "/auth/login";
+  let lastToken: string | null = null;
+
+  return {
+    login: async ({ username, password }: { username: string; password: string }) => {
+      const response = await client.post<{ access_token: string; refresh_token: string }>(
+        loginPath,
+        { email: username, password },
+      );
+      client.setTokens({
+        accessToken: response.access_token,
+        refreshToken: response.refresh_token,
+      });
+      lastToken = response.access_token;
+    },
+
+    logout: async () => {
+      client.logout();
+      lastToken = null;
+    },
+
+    checkAuth: async () => {
+      if (!lastToken || isTokenExpired(lastToken)) {
+        throw new Error("Token expired or missing");
+      }
+    },
+
+    checkError: async (error: { status?: number }) => {
+      if (error.status === 401) {
+        client.logout();
+        lastToken = null;
+        throw new Error("Unauthorized");
+      }
+      // 403 = valid token but no permission - don't logout
+      if (error.status === 403) {
+        throw new Error("Forbidden");
+      }
+    },
+
+    getPermissions: async () => {
+      if (!lastToken) return { roles: [], permissions: [] };
+      const payload = getPayload(lastToken);
+      if (!payload) return { roles: [], permissions: [] };
+      return {
+        roles: payload.roles ?? [],
+        permissions: payload.permissions ?? [],
+      };
+    },
+
+    getIdentity: async () => {
+      if (!lastToken) throw new Error("Not authenticated");
+      const payload = getPayload(lastToken);
+      if (!payload) throw new Error("Invalid token");
+      return {
+        id: payload.sub,
+        fullName: payload.sub,
+        tenant: payload.tenant,
+      };
+    },
+  };
+}

package/src/data-provider.ts

@@ -0,0 +1,140 @@
+/**
+ * React Admin DataProvider using BloqueClient as HTTP transport.
+ *
+ * Translates react-admin CRUD calls to REST endpoints.
+ * Uses `qs` for query string serialization (FastAPI-compatible).
+ *
+ * Tenant context is handled automatically via BloqueClient's
+ * tenant interceptor (call client.setTenantId() to switch tenants).
+ */
+
+import type { DataProvider } from "react-admin";
+import { HttpError } from "react-admin";
+import { stringify } from "qs";
+import type { BloqueClient } from "@ulfblk/api-client";
+import type { DataProviderOptions, ListResponse } from "./types.js";
+
+const BATCH_SIZE = 5;
+
+function defaultSerializer(params: Record<string, unknown>): string {
+  return stringify(params, { arrayFormat: "repeat", skipNulls: true });
+}
+
+async function batchExecute<T>(
+  ids: (string | number)[],
+  fn: (id: string | number) => Promise<T>,
+): Promise<T[]> {
+  const results: T[] = [];
+  for (let i = 0; i < ids.length; i += BATCH_SIZE) {
+    const batch = ids.slice(i, i + BATCH_SIZE);
+    const batchResults = await Promise.all(batch.map(fn));
+    results.push(...batchResults);
+  }
+  return results;
+}
+
+export function createDataProvider(
+  client: BloqueClient,
+  options?: DataProviderOptions,
+): DataProvider {
+  const base = (options?.basePath ?? "/api").replace(/\/+$/, "");
+  const serialize = options?.querySerializer ?? defaultSerializer;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- react-admin generics are complex
+  type AnyRecord = any;
+
+  async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    try {
+      switch (method) {
+        case "GET":
+          return await client.get<T>(path);
+        case "POST":
+          return await client.post<T>(path, body);
+        case "PUT":
+          return await client.put<T>(path, body);
+        case "DELETE":
+          return await client.delete<T>(path);
+        default:
+          throw new Error(`Unsupported method: ${method}`);
+      }
+    } catch (error: unknown) {
+      if (error instanceof Error && "status" in error) {
+        const e = error as Error & { status: number; body?: unknown };
+        throw new HttpError(e.message, e.status, e.body);
+      }
+      throw error;
+    }
+  }
+
+  return {
+    getList: async (resource: string, params: any) => {
+      const { page, perPage } = params.pagination ?? { page: 1, perPage: 20 };
+      const { field, order } = params.sort ?? { field: "id", order: "ASC" };
+      const query = serialize({
+        page,
+        size: perPage,
+        sort: field,
+        order,
+        ...params.filter,
+      });
+      const url = `${base}/${resource}?${query}`;
+      const response = await request<AnyRecord>("GET", url);
+      return { data: response.items, total: response.total };
+    },
+
+    getOne: async (resource: string, params: any) => {
+      const data = await request<AnyRecord>("GET", `${base}/${resource}/${params.id}`);
+      return { data };
+    },
+
+    getMany: async (resource: string, params: any) => {
+      const query = serialize({ id: params.ids });
+      const response = await request<AnyRecord>("GET", `${base}/${resource}?${query}`);
+      return { data: response.items };
+    },
+
+    getManyReference: async (resource: string, params: any) => {
+      const { page, perPage } = params.pagination ?? { page: 1, perPage: 20 };
+      const { field, order } = params.sort ?? { field: "id", order: "ASC" };
+      const query = serialize({
+        page,
+        size: perPage,
+        sort: field,
+        order,
+        [params.target]: params.id,
+        ...params.filter,
+      });
+      const response = await request<AnyRecord>("GET", `${base}/${resource}?${query}`);
+      return { data: response.items, total: response.total };
+    },
+
+    create: async (resource: string, params: any) => {
+      const data = await request<AnyRecord>("POST", `${base}/${resource}`, params.data);
+      return { data };
+    },
+
+    update: async (resource: string, params: any) => {
+      const data = await request<AnyRecord>("PUT", `${base}/${resource}/${params.id}`, params.data);
+      return { data };
+    },
+
+    delete: async (resource: string, params: any) => {
+      const data = await request<AnyRecord>("DELETE", `${base}/${resource}/${params.id}`);
+      return { data };
+    },
+
+    deleteMany: async (resource: string, params: any) => {
+      await batchExecute(params.ids, (id) =>
+        request("DELETE", `${base}/${resource}/${id}`),
+      );
+      return { data: params.ids };
+    },
+
+    updateMany: async (resource: string, params: any) => {
+      await batchExecute(params.ids, (id) =>
+        request("PUT", `${base}/${resource}/${id}`, params.data),
+      );
+      return { data: params.ids };
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @ulfblk/admin - React Admin providers for the ulfblk ecosystem.
+ *
+ * Provides DataProvider and AuthProvider that use BloqueClient
+ * as the HTTP transport layer, with automatic tenant context,
+ * JWT auth, and FastAPI-compatible query serialization.
+ */
+
+export { createDataProvider } from "./data-provider.js";
+export { createAuthProvider } from "./auth-provider.js";
+export type { DataProviderOptions, AuthProviderOptions, ListResponse } from "./types.js";

package/src/types.ts

@@ -0,0 +1,33 @@
+/**
+ * Configuration options for the ulfblk DataProvider.
+ */
+export interface DataProviderOptions {
+  /** Base path for API endpoints. Default: "/api" */
+  basePath?: string;
+
+  /**
+   * Custom query string serializer.
+   * Default uses `qs` with arrayFormat: 'repeat' (FastAPI-compatible).
+   */
+  querySerializer?: (params: Record<string, unknown>) => string;
+}
+
+/**
+ * Configuration options for the ulfblk AuthProvider.
+ */
+export interface AuthProviderOptions {
+  /** Path for the login endpoint. Default: "/auth/login" */
+  loginPath?: string;
+}
+
+/**
+ * Expected response format from list endpoints.
+ * Must match PaginatedResponse from the Python backend.
+ */
+export interface ListResponse<T = Record<string, unknown>> {
+  items: T[];
+  total: number;
+  page?: number;
+  page_size?: number;
+  pages?: number;
+}