@fayz-ai/db 0.9.0 → 0.11.0

package/migrations/034_custom_fields.sql

@@ -0,0 +1,55 @@
+-- ============================================================================
+-- 034 — custom_fields: the tenant's own fields, on every core record.
+--
+-- The rule this exists to make true: customization lives in DATA, never in
+-- schema. Every tenant in a pool shares one identical schema — no per-tenant
+-- DDL, no schema branch. A merchant asking for "tipo de pele on the client
+-- record" gets an INSERT into plg_entity_fields (035), not a migration.
+--
+-- Why a column and not `metadata`: metadata is the system's bag (a block's
+-- title, an order's direction, Google's etag). custom_fields is the merchant's
+-- content, and only it is governed by the registry. Keeping them apart is what
+-- lets a future connector ship "this tenant's fields" as one predictable
+-- payload instead of guessing which keys are internal.
+--
+-- All eleven archetypes at once. A partial rollout produces "works on the
+-- entities somebody remembered", which is the failure mode 026 refused when it
+-- declined to put an audit trigger on one table at a time.
+--
+-- Idempotent.
+-- ============================================================================
+
+ALTER TABLE public.people            ADD COLUMN IF NOT EXISTS custom_fields jsonb NOT NULL DEFAULT '{}'::jsonb;
+ALTER TABLE public.categories        ADD COLUMN IF NOT EXISTS custom_fields jsonb NOT NULL DEFAULT '{}'::jsonb;
+ALTER TABLE public.products          ADD COLUMN IF NOT EXISTS custom_fields jsonb NOT NULL DEFAULT '{}'::jsonb;
+ALTER TABLE public.services          ADD COLUMN IF NOT EXISTS custom_fields jsonb NOT NULL DEFAULT '{}'::jsonb;
+ALTER TABLE public.orders            ADD COLUMN IF NOT EXISTS custom_fields jsonb NOT NULL DEFAULT '{}'::jsonb;
+ALTER TABLE public.order_items       ADD COLUMN IF NOT EXISTS custom_fields jsonb NOT NULL DEFAULT '{}'::jsonb;
+ALTER TABLE public.transactions      ADD COLUMN IF NOT EXISTS custom_fields jsonb NOT NULL DEFAULT '{}'::jsonb;
+ALTER TABLE public.appointments      ADD COLUMN IF NOT EXISTS custom_fields jsonb NOT NULL DEFAULT '{}'::jsonb;
+ALTER TABLE public.appointment_items ADD COLUMN IF NOT EXISTS custom_fields jsonb NOT NULL DEFAULT '{}'::jsonb;
+ALTER TABLE public.schedules         ADD COLUMN IF NOT EXISTS custom_fields jsonb NOT NULL DEFAULT '{}'::jsonb;
+ALTER TABLE public.locations         ADD COLUMN IF NOT EXISTS custom_fields jsonb NOT NULL DEFAULT '{}'::jsonb;
+
+COMMENT ON COLUMN public.people.custom_fields IS
+  'Fields this tenant declared for its own records. Keys are governed by '
+  'plg_entity_fields (035) and validated on write; never free-form. Distinct '
+  'from metadata, which is the system''s own bag.';
+
+-- ---------------------------------------------------------------------------
+-- Indexes: only where there is use, and only by platform decision.
+--
+-- The reason `metadata` became unfilterable is not jsonb — it is that no
+-- metadata column in this tree has ever had an index (128 references, zero).
+-- jsonb_path_ops because the filter path compiles to containment (@>), the same
+-- choice and same reason as plg_entity_records_data_gin.
+--
+-- The other eight archetypes carry the column and no index until something
+-- actually queries them. Promoting one is a migration, deliberately.
+-- ---------------------------------------------------------------------------
+CREATE INDEX IF NOT EXISTS people_custom_fields_gin
+  ON public.people USING gin (custom_fields jsonb_path_ops);
+CREATE INDEX IF NOT EXISTS appointments_custom_fields_gin
+  ON public.appointments USING gin (custom_fields jsonb_path_ops);
+CREATE INDEX IF NOT EXISTS products_custom_fields_gin
+  ON public.products USING gin (custom_fields jsonb_path_ops);

package/migrations/035_field_registry.sql

@@ -0,0 +1,148 @@
+-- ============================================================================
+-- 035 — plg_entity_fields: which fields exist, for whom, and what they accept.
+--
+-- The half of 034 that makes custom_fields governed instead of free-form. A key
+-- that is not declared here is refused on write; UI, validation and reports are
+-- generated from these rows, not hardcoded.
+--
+-- tenant_id NULL is the vertical's own vocabulary (the salon anamnesis a pool
+-- ships with); non-null is what ONE merchant defined. Same convention, and the
+-- same reason, as plg_shop_rule_attributes: widening the vocabulary is an
+-- INSERT. Two partial unique indexes keep the halves from colliding.
+--
+-- This is also the AI builder's whole surface for extra fields: a row here, no
+-- DDL, no migration. The column it fills already exists everywhere (034), which
+-- is what makes that boundary enforceable rather than merely stated.
+--
+-- Idempotent.
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS public.plg_entity_fields (
+  id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+
+  -- NULL = the vertical's vocabulary, readable by every tenant in the pool and
+  -- writable by none of them. Non-null = this tenant's own field.
+  tenant_id     uuid REFERENCES public.tenants(id) ON DELETE CASCADE,
+
+  -- The record kind this field lives on: 'person', 'appointment', 'product'…
+  -- No CHECK — the next archetype is a value, not a migration. The closed set
+  -- lives in TS, where it can throw a useful error naming the valid ones.
+  reference     text NOT NULL CHECK (reference ~ '^[a-z][a-z0-9_]*$'),
+
+  -- The key inside custom_fields. IMMUTABLE once written — see the trigger.
+  key           text NOT NULL CHECK (key ~ '^[a-z][a-zA-Z0-9_]*$'),
+
+  -- A closed vocabulary on purpose: a type is a MODEL change (this CHECK, the
+  -- TS union, and every renderer), not an insert. Mirrors ENTITY_FIELD_TYPES.
+  type          text NOT NULL CHECK (type IN (
+                  'text', 'richtext', 'number', 'boolean', 'json',
+                  'image', 'url', 'ref', 'point', 'date', 'datetime', 'select'
+                )),
+
+  label         text,
+  help          text,
+  required      boolean NOT NULL DEFAULT false,
+  default_value jsonb,
+  -- min/max/pattern/enum — read by validateEntityRecordData, not by Postgres.
+  validation    jsonb NOT NULL DEFAULT '{}'::jsonb,
+  -- The choices, when type = 'select'.
+  options       jsonb,
+  position      integer NOT NULL DEFAULT 0,
+
+  -- 'declared' came from code and is re-asserted on every deploy; 'merchant'
+  -- came from the admin with no deploy. A deploy never deletes a merchant row —
+  -- a declared key ADOPTS a colliding merchant key instead.
+  origin        text NOT NULL DEFAULT 'merchant' CHECK (origin IN ('declared', 'merchant')),
+  owner         text,
+
+  -- Soft: a value already written to custom_fields must stay readable after the
+  -- field leaves the form.
+  archived_at   timestamptz,
+
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS plg_entity_fields_core_key
+  ON public.plg_entity_fields (reference, key) WHERE tenant_id IS NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS plg_entity_fields_tenant_key
+  ON public.plg_entity_fields (tenant_id, reference, key) WHERE tenant_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS plg_entity_fields_lookup
+  ON public.plg_entity_fields (tenant_id, reference, position) WHERE archived_at IS NULL;
+
+-- ---------------------------------------------------------------------------
+-- The machine key does not move.
+--
+-- The label is the merchant's to rename whenever they like. The key is the name
+-- of data already written into custom_fields on every record, and the thing an
+-- integration maps to. Renaming it silently orphans every value ever stored.
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION public.plg_entity_fields_key_is_immutable()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = public
+AS $fn$
+BEGIN
+  IF NEW.key IS DISTINCT FROM OLD.key OR NEW.reference IS DISTINCT FROM OLD.reference THEN
+    RAISE EXCEPTION
+      'A chave de máquina de um campo não muda (%.% → %.%). O rótulo é livre; a '
+      'chave é o nome do dado já gravado em custom_fields e o que uma integração '
+      'mapeia. Para trocar, arquive este campo e crie outro.',
+      OLD.reference, OLD.key, NEW.reference, NEW.key;
+  END IF;
+  RETURN NEW;
+END;
+$fn$;
+
+DROP TRIGGER IF EXISTS plg_entity_fields_immutable_key ON public.plg_entity_fields;
+CREATE TRIGGER plg_entity_fields_immutable_key
+  BEFORE UPDATE ON public.plg_entity_fields
+  FOR EACH ROW EXECUTE FUNCTION public.plg_entity_fields_key_is_immutable();
+
+DROP TRIGGER IF EXISTS plg_entity_fields_updated_at ON public.plg_entity_fields;
+CREATE TRIGGER plg_entity_fields_updated_at
+  BEFORE UPDATE ON public.plg_entity_fields
+  FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+-- ---------------------------------------------------------------------------
+-- RLS and the default-privilege trap.
+--
+-- 011 closed `anon` on every table and on future ones. It did NOT close
+-- `authenticated`, which is still born with the full set on any new public
+-- table — here that would be every tenant editing every other tenant's field
+-- definitions. Stripped first, granted back only what is needed (029's block).
+-- ---------------------------------------------------------------------------
+REVOKE ALL ON public.plg_entity_fields FROM anon, authenticated;
+
+ALTER TABLE public.plg_entity_fields ENABLE ROW LEVEL SECURITY;
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.plg_entity_fields TO authenticated;
+
+-- Reads the vertical's vocabulary AND its own. The NULL half is what a pool
+-- ships with, and a tenant has to see it to render a form from it.
+DROP POLICY IF EXISTS plg_entity_fields_member_read ON public.plg_entity_fields;
+CREATE POLICY plg_entity_fields_member_read ON public.plg_entity_fields
+  FOR SELECT TO authenticated
+  USING (tenant_id IS NULL OR tenant_id IN (SELECT public.user_tenant_ids()));
+
+-- Writes only its own. `tenant_id IS NULL` fails these three by construction —
+-- NULL IN (…) is never true — so no merchant can edit the pool's vocabulary.
+DROP POLICY IF EXISTS plg_entity_fields_member_insert ON public.plg_entity_fields;
+CREATE POLICY plg_entity_fields_member_insert ON public.plg_entity_fields
+  FOR INSERT TO authenticated
+  WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()));
+
+DROP POLICY IF EXISTS plg_entity_fields_member_update ON public.plg_entity_fields;
+CREATE POLICY plg_entity_fields_member_update ON public.plg_entity_fields
+  FOR UPDATE TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()))
+  WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()));
+
+DROP POLICY IF EXISTS plg_entity_fields_member_delete ON public.plg_entity_fields;
+CREATE POLICY plg_entity_fields_member_delete ON public.plg_entity_fields
+  FOR DELETE TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+
+COMMENT ON TABLE public.plg_entity_fields IS
+  'Per-tenant field registry for custom_fields (034). tenant_id NULL is the '
+  'vertical vocabulary — readable by every tenant, writable by none.';

package/migrations/036_analytics_run_batch.sql

@@ -0,0 +1,84 @@
+-- ============================================================================
+-- analytics_run_batch — one round trip for a whole dashboard
+-- ----------------------------------------------------------------------------
+-- A card fetches itself. That is the right ownership (a tile added to a pack
+-- must not require editing a page-level query), and it is why opening
+-- /analytics fired FORTY-ONE requests: twenty-two cards, most of them also
+-- asking for the comparison window, each its own POST. Change the date range
+-- and all forty-one go again.
+--
+-- Nothing about the ownership needs to change — only the transport. This takes
+-- an ARRAY of the exact same arguments analytics_run already accepts and
+-- returns the answers in order, so a dashboard is one call and a card is still
+-- the thing that declares its own query.
+--
+-- The engine itself is untouched: every element goes through analytics_run,
+-- which means the allowlist, the identifier guard, the fixed aggregate
+-- vocabulary and SECURITY INVOKER still decide what any of this can read. A
+-- batch cannot reach a row a single call could not.
+--
+-- Per-element failure is contained. One card naming a column that does not
+-- exist must not blank the other twenty-one, so each iteration runs in its own
+-- subtransaction and a failure is RETURNED as {"error", "code"} at that index
+-- rather than raised — which is also what lets the client render one broken
+-- tile beside twenty-one live ones.
+--
+-- Requires 024_analytics_engine.sql. Idempotent.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.analytics_run_batch(p_requests jsonb)
+RETURNS jsonb
+LANGUAGE plpgsql
+STABLE
+AS $$
+DECLARE
+  v_req     jsonb;
+  v_result  jsonb;
+  v_out     jsonb := '[]'::jsonb;
+BEGIN
+  IF p_requests IS NULL OR jsonb_typeof(p_requests) <> 'array' THEN
+    RAISE EXCEPTION 'analytics: batch expects an array of requests' USING ERRCODE = '22023';
+  END IF;
+
+  -- A cap, not a convenience: this is a caller-supplied loop over a function
+  -- that reads tables, and an unbounded array is a way to ask one request to do
+  -- unbounded work. The largest pack in the product is ~30 cards.
+  IF jsonb_array_length(p_requests) > 100 THEN
+    RAISE EXCEPTION 'analytics: batch of % exceeds the limit of 100',
+      jsonb_array_length(p_requests) USING ERRCODE = '22023';
+  END IF;
+
+  FOR v_req IN SELECT * FROM jsonb_array_elements(p_requests)
+  LOOP
+    BEGIN
+      v_result := public.analytics_run(
+        p_source         => v_req ->> 'source',
+        p_tenant_id      => NULLIF(v_req ->> 'tenant_id', '')::uuid,
+        p_from           => NULLIF(v_req ->> 'from', '')::timestamptz,
+        p_to             => NULLIF(v_req ->> 'to', '')::timestamptz,
+        p_dimensions     => COALESCE(v_req -> 'dimensions', '[]'::jsonb),
+        p_measures       => COALESCE(v_req -> 'measures', '[]'::jsonb),
+        p_filters        => COALESCE(v_req -> 'filters', '{}'::jsonb),
+        p_search         => NULLIF(v_req ->> 'search', ''),
+        p_search_columns => CASE
+                              WHEN jsonb_typeof(v_req -> 'search_columns') = 'array'
+                              THEN ARRAY(SELECT jsonb_array_elements_text(v_req -> 'search_columns'))
+                            END,
+        p_sort           => NULLIF(v_req ->> 'sort', ''),
+        p_dir            => COALESCE(NULLIF(v_req ->> 'dir', ''), 'desc'),
+        p_limit          => COALESCE((v_req ->> 'limit')::int, 500),
+        p_offset         => COALESCE((v_req ->> 'offset')::int, 0)
+      );
+    EXCEPTION WHEN OTHERS THEN
+      v_result := jsonb_build_object('error', SQLERRM, 'code', SQLSTATE);
+    END;
+
+    v_out := v_out || jsonb_build_array(v_result);
+  END LOOP;
+
+  RETURN v_out;
+END;
+$$;
+
+REVOKE ALL     ON FUNCTION public.analytics_run_batch(jsonb) FROM public;
+GRANT  EXECUTE ON FUNCTION public.analytics_run_batch(jsonb) TO authenticated, service_role;

package/package.json

@@ -3,7 +3,7 @@
   "fayz": {
     "status": "beta"
   },
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Fayz SDK database layer — Drizzle schema primitives, spine references, and migration helpers shared across plugins.",
   "type": "module",
   "sideEffects": false,
@@ -12,7 +12,6 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
@@ -20,7 +19,6 @@
   },
   "files": [
     "dist",
-    "src",
     "migrations"
   ],
   "dependencies": {
@@ -43,6 +41,9 @@
     "build": "tsup && tsc --emitDeclarationOnly --declaration --declarationMap --noEmit false",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
+    "test": "bash test/run-migrations.sh",
+    "test:migrations": "bash test/run-migrations.sh",
+    "test:negative-control": "bash test/negative-control.sh",
     "clean": "rm -rf dist"
   }
 }

package/dist/helpers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,QAAQ,sGAGqC,CAAA;AAE1D,mFAAmF;AACnF,eAAO,MAAM,UAAU;;;CAGtB,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,SAAS;;CAErB,CAAA"}

package/src/helpers.ts

@@ -1,23 +0,0 @@
-import { uuid, timestamp } from 'drizzle-orm/pg-core'
-import { tenants } from './schema/spine'
-
-/**
- * Canonical tenant-scoping column: `tenant_id uuid NOT NULL REFERENCES
- * public.tenants(id) ON DELETE CASCADE`. Every Ring-1 plugin table uses this
- * so tenancy is identical everywhere (and RLS can assume the column exists).
- */
-export const tenantId = () =>
-  uuid('tenant_id')
-    .notNull()
-    .references(() => tenants.id, { onDelete: 'cascade' })
-
-/** Standard `created_at` / `updated_at` timestamptz pair with `now()` defaults. */
-export const timestamps = {
-  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
-  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
-}
-
-/** Just `created_at` (for append-only / event-style tables). */
-export const createdAt = {
-  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
-}

package/src/index.ts

@@ -1,12 +0,0 @@
-// @fayz-ai/db — shared Drizzle schema layer for the Fayz SDK.
-//
-// Re-exports the spine references (Ring 0) and the column helpers that plugin
-// schemas compose with. Plugins import from here; apps compose plugin schemas
-// in their own drizzle.config.
-// Re-export the Drizzle pg-core builders so apps import them from @fayz-ai/db
-// (one drizzle-orm instance everywhere — avoids dual-copy PgColumn type clashes
-// when an app composes its own tables with @fayz-ai/db spine refs + plugin schema).
-export * from 'drizzle-orm/pg-core'
-
-export { tenants, people, orders, appointments, products, orderItems } from './schema/spine'
-export { tenantId, timestamps, createdAt } from './helpers'

package/src/schema/spine.ts

@@ -1,35 +0,0 @@
-import { pgTable, uuid } from 'drizzle-orm/pg-core'
-
-/**
- * Ring 0 — the core spine, declared as Drizzle *references* only.
- *
- * These tables are owned by the platform (@fayz-ai/saas core) and already exist
- * in every provisioned pool, directly in the `public` schema (industry-pool
- * model — no saas_core schema). We declare a minimal shape here purely so plugin
- * tables can express real foreign keys in TypeScript. They land in the Drizzle
- * *baseline* snapshot (never re-created), so only the `id` FK target is needed —
- * the live columns are authoritative.
- */
-export const tenants = pgTable('tenants', {
-  id: uuid('id').primaryKey(),
-})
-
-export const people = pgTable('people', {
-  id: uuid('id').primaryKey(),
-})
-
-export const orders = pgTable('orders', {
-  id: uuid('id').primaryKey(),
-})
-
-export const appointments = pgTable('appointments', {
-  id: uuid('id').primaryKey(),
-})
-
-export const products = pgTable('products', {
-  id: uuid('id').primaryKey(),
-})
-
-export const orderItems = pgTable('order_items', {
-  id: uuid('id').primaryKey(),
-})