@rjromeoent/ein-supabase

Shared Supabase contract package for EIN-connected apps.

This package is the canonical home for:

• Generated Supabase database types across EIN schemas.
• Type aliases for canonical database-owned enums.
• Registered app slugs and the x-ein-app header helper.
• Shared org-role helpers for core.app_organization_memberships.
• Typed schema-client helpers.

Regenerate database types from the Event Intelligence Network repo root:

npm run generate:supabase-types

Apps should import shared contracts from this package instead of hand-maintaining partial copies of core, rad, booking_engine, launchpad, or other shared schemas.

App-specific role variation should be a small local mapping from canonical CoreOrgRole values. For example, Booking Engine maps owner/admin to its local admin workflow role and member to rep.

Build

From the Event Intelligence Network repo root:

npm install
npm run generate:supabase-types
npm run test:functions
npm run test:db:rad
npm run build:packages
npm run verify:ein-supabase

test:db:rad is an optional integration test suite. It requires DATABASE_URL to point at a disposable or remote Supabase Postgres database and each SQL test runs inside a transaction that rolls back its fixtures. It proves the RAD Booking offer-context consumer RPC updates both the read model and event consumer offset against real database constraints, and it validates RAD decision integrity rules such as append-only decision logs and offer-created/link consistency. It also verifies app-scoped RAD RLS blocks cross-organization decision-log reads under the authenticated role.

Or from this package directory:

npm run clean
npm run build

The package publishes compiled ESM and declarations from dist.

Publish

This package is intended to be installed by independent Lovable app repos, so apps should not depend on file:../Event-Intelligence-Network/... outside local development.

Publish from the EIN repo root after the rjromeoent npm organization is available to the publishing user, types are regenerated, and the package build passes:

npm run verify:ein-supabase
npm run pack:ein-supabase
npm run publish:ein-supabase

verify:ein-supabase regenerates Supabase types, fails if the generated database contract is not committed, runs Deno edge-function tests, builds the package, and runs an npm pack dry-run. The rollbacked DB integration test is kept as an explicit script because it needs a live Postgres connection. Publishing should not happen from unverified or locally drifted schema types.

The package is configured as a public scoped package. That is intentional for Lovable apps: app deploys can install it without an npm auth token. Do not put secrets, service-role keys, database passwords, or private environment values in this package.

Then app repos should depend on the released version:

{
  "dependencies": {
    "@rjromeoent/ein-supabase": "^0.1.2"
  }
}

Use semver intentionally:

• Patch: regenerated types, additive helpers, docs.
• Minor: additive contracts or new schemas/functions.
• Major: renamed or removed contracts, breaking permission/app context changes.

Package Boundary

This package is the shared contract layer between Event Intelligence Network and independent app repos. It should stay small, stable, and backend-oriented.

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.

Database-Owned Enum Aliases

Examples:

• CoreArtistGenre
• RadDbAvailabilityStatus
• RadDbAssignmentState
• RadDbDecisionType
• BookingOfferStatus

Why:

These are type aliases over generated Supabase enum types. They give apps a stable import name for canonical database-owned values without copying enum strings into each app.

Use these aliases at API, adapter, and database-boundary layers when the value is the raw backend contract:

import type { RadDbDecisionType } from "@rjromeoent/ein-supabase";

interface DecisionRow {
  decision_type: RadDbDecisionType | null;
}

Do not use these aliases for app-specific display buckets or UI commands. For example, RAD's dashboard label "Available" and command action "shortlist" are app vocabulary, while database values like available and shortlisted are backend vocabulary.

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:

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.