@selvajs/supabase-provider 0.14.3 → 0.14.4-beta.0

package/src/data/query.ts

@@ -0,0 +1,22 @@
+/**
+ * Small query-builder helpers shared across Supabase stores.
+ */
+
+/**
+ * The slice of a PostgREST filter builder these helpers touch: an `.is()`
+ * method that returns the same builder for chaining. Generic over the builder
+ * type so the caller's concrete builder (and its row generic) flows through.
+ */
+interface DeletableQuery {
+	is(column: string, value: null): this;
+}
+
+/**
+ * Apply the soft-delete filter `deleted_at IS NULL`. The `.is('deleted_at', null)`
+ * idiom is repeated across every store that soft-deletes; this names it.
+ *
+ *   let q = notDeleted(client.from('projects').select(COLS));
+ */
+export function notDeleted<Q extends DeletableQuery>(query: Q): Q {
+	return query.is('deleted_at', null);
+}

package/src/data/rowStamp.ts

@@ -0,0 +1,48 @@
+import type { RequestContext } from '@selvajs/platform';
+import { auditSoftDelete } from '@selvajs/platform';
+
+/**
+ * Row-level (snake_case) audit-stamp helpers for Supabase stores.
+ *
+ * Platform's `auditUpdate` / `auditSoftDelete` emit camelCase *domain* fields
+ * (`updatedAt` / `updatedBy`), but Postgres rows are snake_case, so every store
+ * hand-translated them. These helpers own that translation once. Row-column
+ * naming is a provider concern, so they live here rather than in platform.
+ *
+ * Two deliberate rules, matched to how the engine's stores already write rows:
+ *  - `updated_by` is written ONLY when `ctx.userId` is set. On system contexts
+ *    it's the empty string, and the column FKs `auth.users(id)` with
+ *    `ON DELETE SET NULL` — writing `''` would violate the FK, so it's omitted
+ *    and the existing value is left untouched.
+ *  - Plain updates DON'T stamp `updated_at`: a per-table `updated_at` trigger
+ *    already sets it. Only the soft-delete stamp writes `updated_at` explicitly,
+ *    so it matches `deleted_at` (a single timestamp for the deletion event).
+ */
+
+/**
+ * Stamp for a plain UPDATE: `{ updated_by }` when the context carries a user,
+ * `{}` otherwise (the DB trigger handles `updated_at`). Spread into the row:
+ * `const row = { ...patch, ...stampUpdate(ctx) }`.
+ */
+export function stampUpdate(ctx: RequestContext): { updated_by?: string } {
+	return ctx.userId ? { updated_by: ctx.userId } : {};
+}
+
+/**
+ * Stamp for a soft-delete: `{ deleted_at, updated_at, updated_by? }`. `updated_at`
+ * is set explicitly to equal `deleted_at`; `updated_by` follows the same
+ * omit-when-empty rule as {@link stampUpdate}. `fallbackActor` defaults to
+ * `ctx.userId` (matching the engine stores' `auditSoftDelete(ctx, ctx.userId)`).
+ */
+export function stampSoftDelete(
+	ctx: RequestContext,
+	fallbackActor: string | null | undefined = ctx.userId
+): { deleted_at: string; updated_at: string; updated_by?: string } {
+	const stamp = auditSoftDelete(ctx, fallbackActor);
+	const row: { deleted_at: string; updated_at: string; updated_by?: string } = {
+		deleted_at: stamp.deletedAt,
+		updated_at: stamp.updatedAt
+	};
+	if (stamp.updatedBy) row.updated_by = stamp.updatedBy;
+	return row;
+}

package/src/index.ts

@@ -12,9 +12,27 @@ export {
 	SupabaseEventSink,
 	SupabaseSolveMetricSink,
 	SupabaseAuditQuery,
-	buildClientBundle
+	buildClientBundle,
+	clientBundleFromEnv,
+	DEFAULT_SCHEMA,
+	mapPostgrestError,
+	stampUpdate,
+	stampSoftDelete,
+	notDeleted,
+	toRange,
+	orderColumn,
+	nextCursorFromRange,
+	encodeCursor,
+	decodeCursor
+} from './data/index.js';
+export type {
+	ClientBundle,
+	BuildClientOptions,
+	ForRequestOptions,
+	SchemaClient,
+	SelvaSchemaClient,
+	RangeSpec
 } from './data/index.js';
-export type { ClientBundle, BuildClientOptions } from './data/index.js';
 
 export { SupabaseUserProfileProvider } from './userProfile/index.js';
 

package/supabase/migrations/20260711120000_selva_definition_schema_version.sql

@@ -0,0 +1,18 @@
+-- ============================================================================
+-- Expose the cached schema's format version as a queryable column (ADR 0005).
+--
+-- The stored `schema` blob is a disposable cache of the compute-extracted UI
+-- schema; its embedded `schemaVersion` says which schema format it was written
+-- in. A GENERATED column keeps that version queryable for ops ("how many
+-- versions are stale?") with zero write-path involvement — it can never drift
+-- from the blob, and rows whose schema is NULL (pre-caching uploads) yield
+-- NULL. The web render path re-extracts from compute on version mismatch; it
+-- reads the version from the blob itself, not from this column.
+-- ============================================================================
+
+alter table selva.definition_versions
+	add column if not exists schema_version text
+		generated always as (schema ->> 'schemaVersion') stored;
+
+comment on column selva.definition_versions.schema_version is
+	'Schema format version of the cached `schema` blob (generated from schema->>''schemaVersion''). NULL when no schema is cached. Ops/diagnostics only — the app reads the version from the blob.';