@fayz-ai/core 0.1.6 → 0.1.7

package/README.md

@@ -0,0 +1,44 @@
+# @fayz-ai/core
+
+> The headless kernel that turns plugin manifests into a running app.
+
+[![npm](https://img.shields.io/npm/v/@fayz-ai/core.svg)](https://www.npmjs.com/package/@fayz-ai/core)
+[![license](https://img.shields.io/npm/l/@fayz-ai/core.svg)](https://github.com/FayaLabs/fayz-sdk/blob/main/LICENSE)
+
+A salon, a restaurant, and a clinic are the same engine with different plugins enabled. `@fayz-ai/core` is that engine — headless and UI-free. It defines the plugin contract, the entity/CRUD model, the data-provider abstraction, and the manifest format that describes an entire app as data. Plugins declare what they are; core resolves them into navigation, routes, widgets, and tools at runtime.
+
+The bet: a SaaS app should be composable and portable, not hand-wired. Swap Supabase for the Fayz API or a mock with one provider call. Describe an app as a manifest and render it. Register an entity once and get list/form/detail behavior everywhere. Core is the substrate that makes plugins "snap in."
+
+## What's inside
+- **Plugin runtime** — `definePlugin`, `resolvePluginRuntime`, `getWidgetsForZone`, `getDashboardWidgets`, `PluginRuntimeProvider`, `PLUGIN_API_VERSION`
+- **Data providers** — `createSupabaseProvider`, `createFayzApiProvider`, `createMockProvider`, `createArchetypeProvider`, `withCache`, `resolveDataProvider` over one `DataProvider` interface
+- **Entity + registry** — `registerEntity`, `getEntityByKey`, and the uniform `Registry` for components, blocks, pages, metrics, scaffolds, and plugin factories
+- **App manifest** — `defineApp`, `renderApp`, `migrateManifest`, `validateManifest`, JSON schema, and a versioned migration runner
+- **Blocks** — `BlockRenderer` / `renderBlocks`, the universal page primitive
+- **i18n + router** — `I18nProvider`, `useTranslation`, `hashRouterAdapter`, `windowRouterAdapter`
+- **Event bus + utils** — `eventBus`, `useOnEvent`, `formatCurrency`, `exportCSV`, tenant context (`setActiveTenantId`)
+
+## Install
+```bash
+npm install @fayz-ai/core
+```
+Peer deps: `react`, `react-dom` (^18 or ^19).
+
+## Usage
+```ts
+import { definePlugin, createSupabaseProvider } from '@fayz-ai/core'
+
+const provider = createSupabaseProvider({ url, anonKey })
+
+export const crmPlugin = definePlugin({
+  id: 'crm',
+  navigation: [{ label: 'Clients', path: '/clients' }],
+  entities: [/* declarative data models */],
+})
+```
+
+## Part of the Fayz SDK
+The headless core. `@fayz-ai/auth`, `@fayz-ai/ui`, and `@fayz-ai/saas` build the running app on top of it.
+
+## Roadmap & contributing
+Built and evolving in the open. See the [Fayz SDK roadmap](../../docs/ROADMAP.md#core) for current gaps, missing features, and good first issues.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fayz-ai/core",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Fayz SDK core — data providers, entity system, plugin runtime, i18n, routing",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/data/archetype.ts

@@ -92,16 +92,27 @@ export function createArchetypeProvider<T extends { id: string }>(
   }
   const viewName = VIEW_MAP[config.projectTable] ?? `v_${config.projectTable}`
 
+  // Pure-archetype entity: the project table IS the archetype base (e.g. a
+  // customers list configured with `table: 'persons'`, no separate public
+  // extension table). Read/write saas_core.<base> directly — there is no public
+  // extension row and no v_ view to join. Extension-table entities (clients,
+  // staff_members, …) are unaffected.
+  const isPure = config.projectTable === ac.table
+
   return {
     async list(query: CrudQuery): Promise<CrudResult<T>> {
       const tenantId = config.tenantId()
       if (!tenantId) return { data: [], total: 0 }
 
-      // Single query via v_ view (JOINs public table with saas_core archetype)
-      let q = getClient()
-        .from(viewName)
-        .select('*', { count: 'exact' })
-        .eq('tenant_id', tenantId)
+      // Pure archetype → read saas_core.<base> directly (filtered by kind);
+      // otherwise the v_ view (JOINs public extension with saas_core archetype).
+      let q = isPure
+        ? coreClient().from(ac.table).select('*', { count: 'exact' }).eq('tenant_id', tenantId)
+        : getClient().from(viewName).select('*', { count: 'exact' }).eq('tenant_id', tenantId)
+
+      if (isPure && HAS_KIND.has(config.archetype)) {
+        q = q.eq('kind', config.archetypeKind)
+      }
 
       // Search
       if (query.search && config.searchColumns && config.searchColumns.length > 0) {
@@ -155,20 +166,23 @@ export function createArchetypeProvider<T extends { id: string }>(
       if (archetypeError) throw archetypeError
       const archetypeId = (archetypeRow as any).id
 
-      // 2. Insert into project table with archetype FK as PK
-      projectData[fkColumn] = archetypeId
-      projectData.tenant_id = tenantId
+      // 2. Insert into project table with archetype FK as PK.
+      //    Pure-archetype entities have no extension table — skip this step.
+      if (!isPure) {
+        projectData[fkColumn] = archetypeId
+        projectData.tenant_id = tenantId
 
-      const { error: projectError } = await getClient()
-        .from(config.projectTable)
-        .insert(projectData)
+        const { error: projectError } = await getClient()
+          .from(config.projectTable)
+          .insert(projectData)
 
-      if (projectError) {
-        await coreClient().from(ac.table).delete().eq('id', archetypeId)
-        throw projectError
+        if (projectError) {
+          await coreClient().from(ac.table).delete().eq('id', archetypeId)
+          throw projectError
+        }
       }
 
-      return { id: archetypeId, ...archetypeRow, ...projectData } as unknown as T
+      return { id: archetypeId, ...archetypeRow, ...(isPure ? {} : projectData) } as unknown as T
     },
 
     async update(id, data) {
@@ -182,7 +196,7 @@ export function createArchetypeProvider<T extends { id: string }>(
         if (error) throw error
       }
 
-      if (Object.keys(projectData).length > 0) {
+      if (!isPure && Object.keys(projectData).length > 0) {
         const { error } = await getClient()
           .from(config.projectTable)
           .update(projectData)
@@ -190,8 +204,11 @@ export function createArchetypeProvider<T extends { id: string }>(
         if (error) throw error
       }
 
-      // Re-fetch
+      // Re-fetch (archetype only for pure entities; otherwise join the extension)
       const { data: archetypeRow } = await coreClient().from(ac.table).select('*').eq('id', id).single()
+      if (isPure) {
+        return mapRow<T>({ ...archetypeRow, id } as Record<string, unknown>)
+      }
       const { data: projectRow } = await getClient().from(config.projectTable).select('*').eq(fkColumn, id).single()
 
       const flat = { ...archetypeRow, ...projectRow, id }