@rjromeoent/ein-supabase 0.1.0 → 0.1.1

package/README.md

@@ -79,13 +79,253 @@ Use semver intentionally:
 - Minor: additive contracts or new schemas/functions.
 - Major: renamed or removed contracts, breaking permission/app context changes.
 
-## Consumer Rule
+## Package Boundary
 
-App repos may keep their UI-specific adapters and view models locally, but
-shared backend contracts belong here first:
+This package is the shared contract layer between Event Intelligence Network and
+independent app repos. It should stay small, stable, and backend-oriented.
 
-- generated `Database` types
-- app slugs and `x-ein-app`
-- canonical org roles and permission helpers
-- Edge Function request/response contracts
-- shared runtime guards that protect persisted JSON or Edge response boundaries
+Use this rule:
+
+> Put a thing in this package only when more than one app should depend on the
+> same backend contract or helper. Keep app workflow, UI, and feature-specific
+> shapes inside the app until reuse is real.
+
+### Belongs In This Package
+
+#### Generated Database Types
+
+Examples:
+
+- `Database`
+- schema table/view/function types generated from EIN Supabase
+- schema-aware Supabase helpers like `schemaClient`
+
+Why:
+
+These represent the actual EIN database contract. Every connected app should
+compile against the same source of truth instead of copying partial generated
+types.
+
+#### App Registry And Request Context
+
+Examples:
+
+- `EIN_APP_SLUGS`
+- `EIN_APP_HEADER`
+- `einAppHeaders("rad")`
+
+Why:
+
+RLS policies and app-scoped RPCs depend on the same `x-ein-app` slug everywhere.
+If each app hand-types the slug/header, policy mismatches are easy to create and
+hard to debug.
+
+#### Shared Auth And Organization Vocabulary
+
+Examples:
+
+- `CoreOrgRole`
+- role helpers for `core.app_organization_memberships`
+- helpers that answer "can this user access this app/org?"
+
+Why:
+
+All apps should interpret core org membership the same way. An app can map
+canonical roles to local workflow roles, but the canonical role vocabulary
+belongs here.
+
+Example local mapping:
+
+```ts
+import type { CoreOrgRole } from "@rjromeoent/ein-supabase";
+
+type BookingWorkflowRole = "admin" | "rep" | "viewer";
+
+export function mapBookingRole(role: CoreOrgRole): BookingWorkflowRole {
+  if (role === "owner" || role === "admin") return "admin";
+  if (role === "member") return "rep";
+  return "viewer";
+}
+```
+
+#### Generic JSON Guards
+
+Examples:
+
+- `isJsonRecord`
+- `toJsonRecord`
+- `stringOrNull`
+- `numberOrNull`
+- `booleanOrFalse`
+- `stringArrayOrEmpty`
+
+Why:
+
+Every EIN-connected app reads JSON metadata, Edge Function payloads, and
+Supabase JSON columns. These low-level primitives are generic, stable, and not
+tied to any app workflow. Keeping them here avoids each app recreating slightly
+different JSON parsing behavior.
+
+These helpers should stay small and dependency-free. App-specific parsers should
+compose them locally.
+
+#### Cross-App Backend Contracts
+
+Examples:
+
+- one RPC request/response type consumed by Atlas and RAD
+- one Edge Function request/response type consumed by Launchpad and Event Ops
+- canonical event-bus envelope types used by multiple apps
+
+Why:
+
+When two or more apps call the same backend function, keeping the contract here
+prevents drift. A backend breaking change should become one package version
+change, not several unrelated app edits.
+
+Promotion test:
+
+- Is the backend endpoint used by more than one app today?
+- Would a contract drift bug affect more than one app?
+- Is the payload stable enough that changing it should require a package
+  version bump?
+
+If the answer is yes, it belongs here.
+
+#### Shared Status Vocabularies
+
+Examples:
+
+- canonical app slugs
+- canonical org roles
+- shared lifecycle statuses consumed across multiple apps
+- shared event-bus event names
+
+Why:
+
+String vocabularies are high-risk drift points. If multiple apps compare the
+same status string, the source of truth should be shared.
+
+### Belongs In The App
+
+#### Feature View Models
+
+Examples:
+
+- RAD dashboard row models
+- Atlas artist search result cards
+- Launchpad event hierarchy screen state
+- Event Ops table/filter state
+
+Why:
+
+These are presentation shapes. They change as the UI changes and should not
+force package releases.
+
+#### App-Specific Edge Function Contracts
+
+Examples:
+
+- `rad-get-event-edition-grid`
+- `rad-get-artist-availability-context`
+- `rad-capture-search-snapshot`
+- RAD saved event edition view payloads
+
+Why:
+
+These are RAD workflow contracts. They include UI restoration state, snapshots,
+and RAD-specific orchestration. They should stay in RAD until another app
+actually consumes the same payload.
+
+If Event Ops or Atlas later needs the exact same contract, promote the stable
+request/response shape into this package and update both apps to import it.
+
+#### Adapters And Runtime Normalizers
+
+Examples:
+
+- `adaptEventEditionGrid`
+- `adaptSearchResults`
+- `adaptArtistAvailabilityContext`
+- local parsing of nullable dates for UI display
+- `parseSearchFilters`
+- `isSearchResultSet`
+
+Why:
+
+Adapters convert backend transport into app/domain/view models. That conversion
+usually reflects app-specific UI decisions. Share only small generic helpers
+when multiple apps need identical parsing behavior.
+
+#### App-Specific Permission Mapping
+
+Examples:
+
+- Booking Engine maps `owner/admin` to local `admin`
+- Booking Engine maps `member` to local `rep`
+- RAD maps org roles to internal/client mode affordances
+
+Why:
+
+Core org roles are shared. Workflow permissions are app-specific. Keep the
+canonical role type here, but keep local permission policy near the feature that
+uses it unless the same policy is shared.
+
+#### Persisted UI State And Snapshots
+
+Examples:
+
+- RAD saved search filter payloads
+- RAD search snapshot result blobs
+- RAD saved event edition grid snapshots
+- dashboard state tokens
+
+Why:
+
+These are intentionally flexible JSON blobs for restoring app state. They are
+not stable backend schema contracts and should not be versioned through the
+shared package unless multiple apps must read/write the same blob format.
+
+### Decision Checklist
+
+Before adding a type/helper to this package, answer:
+
+1. Is it sourced from EIN backend schema, auth, RLS, app registry, or a shared
+   backend endpoint?
+2. Is it used by at least two apps, or is it foundational enough that every app
+   should use the same implementation?
+3. Would duplicating it in apps create real drift or security risk?
+4. Is it stable enough to version with semver?
+5. Does it avoid app UI state, feature-specific view models, and one-off screen
+   behavior?
+
+Add it here only when the answer is yes to the relevant shared-contract
+questions. Otherwise, keep it local in the app and revisit when reuse appears.
+
+### Examples
+
+| Item | Location | Reason |
+| --- | --- | --- |
+| `Database` generated Supabase type | Package | Every app should use the same DB schema contract. |
+| `EIN_APP_SLUGS.rad` | Package | RLS/app policies require consistent slugs. |
+| `CoreOrgRole` | Package | Org role meaning must be consistent across apps. |
+| `schemaClient(supabase, "rad")` | Package | Shared typed helper for schema-scoped Supabase access. |
+| `rad-get-event-edition-grid` response | RAD app | RAD-only workflow and UI grid payload today. |
+| RAD saved search filters | RAD app | Persisted UI state blob, not a shared backend contract. |
+| Booking Engine role-to-workflow mapping | Booking app | Local workflow interpretation of shared core role. |
+| Event bus envelope used by all apps | Package | Cross-app backend integration contract. |
+| ARTEMIS recommendation card view model | RAD app | Presentation model, not shared transport. |
+
+### Promotion Process
+
+When a local app contract becomes shared:
+
+1. Move the stable request/response or vocabulary into this package.
+2. Export it from `src/index.ts`.
+3. Add README usage notes if the boundary is non-obvious.
+4. Bump package version:
+   - patch for regenerated/additive types
+   - minor for new shared contracts
+   - major for renamed/removed/breaking contracts
+5. Update all consuming apps to import from the package.
+6. Remove local duplicate types from app repos.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./app-context.js";
 export * from "./auth.js";
+export * from "./json.js";
 export * from "./schema-client.js";
 export type { Constants, Database, Enums, Json, Tables, TablesInsert, TablesUpdate, } from "./generated/database.types.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from "./app-context.js";
 export * from "./auth.js";
+export * from "./json.js";
 export * from "./schema-client.js";

package/dist/json.d.ts

@@ -0,0 +1,13 @@
+export type JsonRecord = Record<string, unknown>;
+export declare function isJsonRecord(value: unknown): value is JsonRecord;
+export declare function toJsonRecord(value: unknown): JsonRecord;
+export declare function stringValue(value: unknown): string | undefined;
+export declare function stringOrNull(value: unknown): string | null;
+export declare function nullableStringValue(value: unknown): string | null | undefined;
+export declare function numberValue(value: unknown): number | undefined;
+export declare function numberOrNull(value: unknown): number | null;
+export declare function booleanValue(value: unknown): boolean | undefined;
+export declare function booleanOrNull(value: unknown): boolean | null;
+export declare function booleanOrFalse(value: unknown): boolean;
+export declare function stringArrayValue(value: unknown): string[] | undefined;
+export declare function stringArrayOrEmpty(value: unknown): string[];

package/dist/json.js

@@ -0,0 +1,40 @@
+export function isJsonRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function toJsonRecord(value) {
+    return isJsonRecord(value) ? value : {};
+}
+export function stringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+export function stringOrNull(value) {
+    return stringValue(value) ?? null;
+}
+export function nullableStringValue(value) {
+    return value === null ? null : stringValue(value);
+}
+export function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? value
+        : undefined;
+}
+export function numberOrNull(value) {
+    return numberValue(value) ?? null;
+}
+export function booleanValue(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+export function booleanOrNull(value) {
+    return booleanValue(value) ?? null;
+}
+export function booleanOrFalse(value) {
+    return value === true;
+}
+export function stringArrayValue(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : undefined;
+}
+export function stringArrayOrEmpty(value) {
+    return stringArrayValue(value) ?? [];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rjromeoent/ein-supabase",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Shared Supabase types, app context, and contract helpers for EIN-connected apps.",
   "type": "module",
   "sideEffects": false,