@enterstellar-ai/adapter-firebase 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,235 @@
+import { AuthAdapter, DataAdapter } from '@enterstellar-ai/types';
+import { Auth } from 'firebase/auth';
+import { Firestore } from 'firebase/firestore';
+
+/**
+ * @module @enterstellar-ai/adapter-firebase/types
+ * @description Configuration types for Firebase adapter factories.
+ *
+ * These types define the input shapes consumers pass to
+ * `createFirebaseAuthAdapter()` and `createFirebaseDataAdapter()`.
+ * The factories map Firebase SDK calls to Enterstellar adapter interfaces.
+ *
+ * @see Bible §4.15
+ * @see Design Choice AD1 — minimal but complete: getSession, hasRole, onAuthChange
+ */
+
+/**
+ * Configuration for {@link createFirebaseAuthAdapter}.
+ *
+ * Takes a Firebase `Auth` instance and optional overrides. The factory maps
+ * Firebase auth calls to the Enterstellar `AuthAdapter` interface.
+ *
+ * @example
+ * ```ts
+ * import { getAuth } from 'firebase/auth';
+ * import { createFirebaseAuthAdapter } from '@enterstellar-ai/adapter-firebase';
+ *
+ * const auth = getAuth(app);
+ * const adapter = createFirebaseAuthAdapter({ auth });
+ * ```
+ */
+type FirebaseAuthConfig = {
+    /**
+     * The Firebase Auth instance.
+     * Must be initialized with `getAuth()` from `firebase/auth`.
+     */
+    readonly auth: Auth;
+    /**
+     * Human-readable adapter name for error messages and DevTools display.
+     * @default `'firebase-auth'`
+     */
+    readonly name?: string;
+    /**
+     * Custom role extraction function.
+     *
+     * Called with the raw Firebase `User` object after a successful auth check.
+     * Returns an array of role strings for RBAC zone gating.
+     *
+     * @default Extracts from `getIdTokenResult().claims.roles` (falls back to `[]`).
+     * @param user - The raw Firebase user object.
+     * @returns Array of role strings (e.g., `['clinician', 'admin']`).
+     *
+     * @example
+     * ```ts
+     * // Extract roles from custom claims
+     * roleExtractor: (user) => (user as any).customClaims?.roles ?? []
+     * ```
+     */
+    readonly roleExtractor?: (user: unknown) => string[];
+};
+/**
+ * Configuration for {@link createFirebaseDataAdapter}.
+ *
+ * Takes a Firestore instance and optional overrides. The factory maps
+ * Firestore query/mutate/subscribe calls to the Enterstellar `DataAdapter` interface.
+ *
+ * @example
+ * ```ts
+ * import { getFirestore } from 'firebase/firestore';
+ * import { createFirebaseDataAdapter } from '@enterstellar-ai/adapter-firebase';
+ *
+ * const firestore = getFirestore(app);
+ * const data = createFirebaseDataAdapter({ firestore });
+ * ```
+ */
+type FirebaseDataConfig = {
+    /**
+     * The Firestore instance.
+     * Must be initialized with `getFirestore()` from `firebase/firestore`.
+     */
+    readonly firestore: Firestore;
+    /**
+     * Human-readable adapter name for error messages and DevTools display.
+     * @default `'firebase-data'`
+     */
+    readonly name?: string;
+};
+
+/**
+ * @module @enterstellar-ai/adapter-firebase/create-firebase-auth-adapter
+ * @description Factory function for creating a Firebase-backed `AuthAdapter`.
+ *
+ * This factory maps Firebase Auth SDK calls to the Enterstellar `AuthAdapter` interface:
+ * - `getSession()` → `auth.currentUser` + `getIdTokenResult()` → `{ userId, roles } | null`
+ * - `hasRole(role)` → `getSession()` → checks `roles.includes(role)`
+ * - `onAuthChange(cb)` → `onAuthStateChanged(auth, cb)` → returns `unsubscribe`
+ *
+ * It builds an `AuthAdapterConfig` and delegates to `createAuthAdapter()` from
+ * `@enterstellar-ai/adapters`, which handles all validation (ENS-7001) and AD5 error
+ * wrapping (ENS-7005 / ENS-7002). This factory is purely an SDK-to-Enterstellar translator.
+ *
+ * ## Role Extraction Strategy
+ *
+ * Firebase stores RBAC roles in custom claims via `getIdTokenResult().claims`.
+ * The default behavior extracts roles from `claims['roles']` (an async operation).
+ * If a custom `roleExtractor` is provided, it is called synchronously with the
+ * raw Firebase `User` object — this enables `onAuthChange()` to include roles
+ * in the callback (since `onAuthChange` is synchronous).
+ *
+ * When no custom `roleExtractor` is provided and `onAuthChange()` fires,
+ * roles default to `[]` in the callback. Full role resolution happens
+ * through `getSession()` or `hasRole()` (which can await `getIdTokenResult()`).
+ *
+ * @see Bible §4.15
+ * @see Design Choice AD1 — minimal but complete: getSession, hasRole, onAuthChange
+ * @see Design Choice AD5 — error wrapping delegated to createAuthAdapter()
+ */
+
+/**
+ * Creates a Firebase-backed `AuthAdapter`.
+ *
+ * Maps Firebase Auth SDK methods to the Enterstellar `AuthAdapter` interface,
+ * then delegates to `createAuthAdapter()` from `@enterstellar-ai/adapters` for
+ * config validation and AD5 error wrapping.
+ *
+ * @param config - Firebase auth configuration with `Auth` instance and optional overrides.
+ * @returns A frozen, validated `AuthAdapter` instance.
+ * @throws `EnterstellarError` with code `ENS-7001` if config validation fails.
+ *
+ * @example
+ * ```ts
+ * import { initializeApp } from 'firebase/app';
+ * import { getAuth } from 'firebase/auth';
+ * import { createFirebaseAuthAdapter } from '@enterstellar-ai/adapter-firebase';
+ *
+ * const app = initializeApp({ projectId: 'my-project', ... });
+ * const firebaseAuth = getAuth(app);
+ *
+ * const auth = createFirebaseAuthAdapter({ auth: firebaseAuth });
+ *
+ * // With custom role extraction (synchronous — enables roles in onAuthChange)
+ * const authWithRoles = createFirebaseAuthAdapter({
+ *   auth: firebaseAuth,
+ *   roleExtractor: (user) => {
+ *     const u = user as { customClaims?: { roles?: string[] } };
+ *     return u.customClaims?.roles ?? [];
+ *   },
+ * });
+ *
+ * // Usage
+ * const session = await auth.getSession();     // { userId, roles } | null
+ * const isAdmin = await auth.hasRole('admin');  // boolean
+ * const unsub = auth.onAuthChange((session) => {
+ *   console.log('Auth state changed:', session);
+ * });
+ * ```
+ */
+declare function createFirebaseAuthAdapter(config: FirebaseAuthConfig): AuthAdapter;
+
+/**
+ * @module @enterstellar-ai/adapter-firebase/create-firebase-data-adapter
+ * @description Factory function for creating a Firestore-backed `DataAdapter`.
+ *
+ * This factory maps Firestore SDK calls to the Enterstellar `DataAdapter` interface:
+ * - `query(resource, params?)` → `getDocs(collection(...))` + `where()` constraints
+ * - `mutate(resource, action, data)` → `addDoc` / `updateDoc` / `deleteDoc`
+ * - `subscribe(resource, cb)` → `onSnapshot(collection(...), cb)` → returns `unsubscribe`
+ *
+ * It builds a `DataAdapterConfig` and delegates to `createDataAdapter()` from
+ * `@enterstellar-ai/adapters`, which handles all validation (ENS-7001) and AD5 error
+ * wrapping (ENS-7003 / ENS-7004 / ENS-7002). This factory is purely an
+ * SDK-to-Enterstellar translator.
+ *
+ * @see Bible §4.15
+ * @see Design Choice AD3 — convention-based dot-notation for resource names
+ * @see Design Choice AD5 — error wrapping delegated to createDataAdapter()
+ */
+
+/**
+ * Creates a Firestore-backed `DataAdapter`.
+ *
+ * Maps Firestore SDK methods to the Enterstellar `DataAdapter` interface,
+ * then delegates to `createDataAdapter()` from `@enterstellar-ai/adapters`
+ * for config validation and AD5 error wrapping.
+ *
+ * @param config - Firestore data configuration with Firestore instance and optional overrides.
+ * @returns A frozen, validated `DataAdapter` instance.
+ * @throws `EnterstellarError` with code `ENS-7001` if config validation fails.
+ *
+ * @example
+ * ```ts
+ * import { initializeApp } from 'firebase/app';
+ * import { getFirestore } from 'firebase/firestore';
+ * import { createFirebaseDataAdapter } from '@enterstellar-ai/adapter-firebase';
+ *
+ * const app = initializeApp({ projectId: 'my-project', ... });
+ * const firestore = getFirestore(app);
+ * const data = createFirebaseDataAdapter({ firestore });
+ *
+ * // Query with filters
+ * const patients = await data.query('patients', { status: 'active' });
+ *
+ * // Mutate — create a document
+ * const newPatient = await data.mutate('patients', 'create', {
+ *   name: 'Jane Doe',
+ *   status: 'active',
+ * });
+ *
+ * // Subscribe to realtime changes
+ * const unsub = data.subscribe('patients', (records) => {
+ *   console.log('Patients updated:', records);
+ * });
+ * ```
+ */
+declare function createFirebaseDataAdapter(config: FirebaseDataConfig): DataAdapter;
+
+/**
+ * @module @enterstellar-ai/adapter-firebase/version
+ * @description Package version constant for `@enterstellar-ai/adapter-firebase`.
+ *
+ * Used by DevTools for version display and runtime compatibility checks.
+ * Must be kept in sync with the `version` field in `package.json`.
+ *
+ * @see Design Choice T14 — version exports
+ */
+/**
+ * Current version of the `@enterstellar-ai/adapter-firebase` package.
+ *
+ * @remarks
+ * This value MUST match the `version` field in `package.json`.
+ * Update this constant whenever a new version is released via Changesets.
+ */
+declare const FIREBASE_ADAPTER_VERSION: "0.0.0";
+
+export { FIREBASE_ADAPTER_VERSION, type FirebaseAuthConfig, type FirebaseDataConfig, createFirebaseAuthAdapter, createFirebaseDataAdapter };

package/dist/index.d.ts

@@ -0,0 +1,235 @@
+import { AuthAdapter, DataAdapter } from '@enterstellar-ai/types';
+import { Auth } from 'firebase/auth';
+import { Firestore } from 'firebase/firestore';
+
+/**
+ * @module @enterstellar-ai/adapter-firebase/types
+ * @description Configuration types for Firebase adapter factories.
+ *
+ * These types define the input shapes consumers pass to
+ * `createFirebaseAuthAdapter()` and `createFirebaseDataAdapter()`.
+ * The factories map Firebase SDK calls to Enterstellar adapter interfaces.
+ *
+ * @see Bible §4.15
+ * @see Design Choice AD1 — minimal but complete: getSession, hasRole, onAuthChange
+ */
+
+/**
+ * Configuration for {@link createFirebaseAuthAdapter}.
+ *
+ * Takes a Firebase `Auth` instance and optional overrides. The factory maps
+ * Firebase auth calls to the Enterstellar `AuthAdapter` interface.
+ *
+ * @example
+ * ```ts
+ * import { getAuth } from 'firebase/auth';
+ * import { createFirebaseAuthAdapter } from '@enterstellar-ai/adapter-firebase';
+ *
+ * const auth = getAuth(app);
+ * const adapter = createFirebaseAuthAdapter({ auth });
+ * ```
+ */
+type FirebaseAuthConfig = {
+    /**
+     * The Firebase Auth instance.
+     * Must be initialized with `getAuth()` from `firebase/auth`.
+     */
+    readonly auth: Auth;
+    /**
+     * Human-readable adapter name for error messages and DevTools display.
+     * @default `'firebase-auth'`
+     */
+    readonly name?: string;
+    /**
+     * Custom role extraction function.
+     *
+     * Called with the raw Firebase `User` object after a successful auth check.
+     * Returns an array of role strings for RBAC zone gating.
+     *
+     * @default Extracts from `getIdTokenResult().claims.roles` (falls back to `[]`).
+     * @param user - The raw Firebase user object.
+     * @returns Array of role strings (e.g., `['clinician', 'admin']`).
+     *
+     * @example
+     * ```ts
+     * // Extract roles from custom claims
+     * roleExtractor: (user) => (user as any).customClaims?.roles ?? []
+     * ```
+     */
+    readonly roleExtractor?: (user: unknown) => string[];
+};
+/**
+ * Configuration for {@link createFirebaseDataAdapter}.
+ *
+ * Takes a Firestore instance and optional overrides. The factory maps
+ * Firestore query/mutate/subscribe calls to the Enterstellar `DataAdapter` interface.
+ *
+ * @example
+ * ```ts
+ * import { getFirestore } from 'firebase/firestore';
+ * import { createFirebaseDataAdapter } from '@enterstellar-ai/adapter-firebase';
+ *
+ * const firestore = getFirestore(app);
+ * const data = createFirebaseDataAdapter({ firestore });
+ * ```
+ */
+type FirebaseDataConfig = {
+    /**
+     * The Firestore instance.
+     * Must be initialized with `getFirestore()` from `firebase/firestore`.
+     */
+    readonly firestore: Firestore;
+    /**
+     * Human-readable adapter name for error messages and DevTools display.
+     * @default `'firebase-data'`
+     */
+    readonly name?: string;
+};
+
+/**
+ * @module @enterstellar-ai/adapter-firebase/create-firebase-auth-adapter
+ * @description Factory function for creating a Firebase-backed `AuthAdapter`.
+ *
+ * This factory maps Firebase Auth SDK calls to the Enterstellar `AuthAdapter` interface:
+ * - `getSession()` → `auth.currentUser` + `getIdTokenResult()` → `{ userId, roles } | null`
+ * - `hasRole(role)` → `getSession()` → checks `roles.includes(role)`
+ * - `onAuthChange(cb)` → `onAuthStateChanged(auth, cb)` → returns `unsubscribe`
+ *
+ * It builds an `AuthAdapterConfig` and delegates to `createAuthAdapter()` from
+ * `@enterstellar-ai/adapters`, which handles all validation (ENS-7001) and AD5 error
+ * wrapping (ENS-7005 / ENS-7002). This factory is purely an SDK-to-Enterstellar translator.
+ *
+ * ## Role Extraction Strategy
+ *
+ * Firebase stores RBAC roles in custom claims via `getIdTokenResult().claims`.
+ * The default behavior extracts roles from `claims['roles']` (an async operation).
+ * If a custom `roleExtractor` is provided, it is called synchronously with the
+ * raw Firebase `User` object — this enables `onAuthChange()` to include roles
+ * in the callback (since `onAuthChange` is synchronous).
+ *
+ * When no custom `roleExtractor` is provided and `onAuthChange()` fires,
+ * roles default to `[]` in the callback. Full role resolution happens
+ * through `getSession()` or `hasRole()` (which can await `getIdTokenResult()`).
+ *
+ * @see Bible §4.15
+ * @see Design Choice AD1 — minimal but complete: getSession, hasRole, onAuthChange
+ * @see Design Choice AD5 — error wrapping delegated to createAuthAdapter()
+ */
+
+/**
+ * Creates a Firebase-backed `AuthAdapter`.
+ *
+ * Maps Firebase Auth SDK methods to the Enterstellar `AuthAdapter` interface,
+ * then delegates to `createAuthAdapter()` from `@enterstellar-ai/adapters` for
+ * config validation and AD5 error wrapping.
+ *
+ * @param config - Firebase auth configuration with `Auth` instance and optional overrides.
+ * @returns A frozen, validated `AuthAdapter` instance.
+ * @throws `EnterstellarError` with code `ENS-7001` if config validation fails.
+ *
+ * @example
+ * ```ts
+ * import { initializeApp } from 'firebase/app';
+ * import { getAuth } from 'firebase/auth';
+ * import { createFirebaseAuthAdapter } from '@enterstellar-ai/adapter-firebase';
+ *
+ * const app = initializeApp({ projectId: 'my-project', ... });
+ * const firebaseAuth = getAuth(app);
+ *
+ * const auth = createFirebaseAuthAdapter({ auth: firebaseAuth });
+ *
+ * // With custom role extraction (synchronous — enables roles in onAuthChange)
+ * const authWithRoles = createFirebaseAuthAdapter({
+ *   auth: firebaseAuth,
+ *   roleExtractor: (user) => {
+ *     const u = user as { customClaims?: { roles?: string[] } };
+ *     return u.customClaims?.roles ?? [];
+ *   },
+ * });
+ *
+ * // Usage
+ * const session = await auth.getSession();     // { userId, roles } | null
+ * const isAdmin = await auth.hasRole('admin');  // boolean
+ * const unsub = auth.onAuthChange((session) => {
+ *   console.log('Auth state changed:', session);
+ * });
+ * ```
+ */
+declare function createFirebaseAuthAdapter(config: FirebaseAuthConfig): AuthAdapter;
+
+/**
+ * @module @enterstellar-ai/adapter-firebase/create-firebase-data-adapter
+ * @description Factory function for creating a Firestore-backed `DataAdapter`.
+ *
+ * This factory maps Firestore SDK calls to the Enterstellar `DataAdapter` interface:
+ * - `query(resource, params?)` → `getDocs(collection(...))` + `where()` constraints
+ * - `mutate(resource, action, data)` → `addDoc` / `updateDoc` / `deleteDoc`
+ * - `subscribe(resource, cb)` → `onSnapshot(collection(...), cb)` → returns `unsubscribe`
+ *
+ * It builds a `DataAdapterConfig` and delegates to `createDataAdapter()` from
+ * `@enterstellar-ai/adapters`, which handles all validation (ENS-7001) and AD5 error
+ * wrapping (ENS-7003 / ENS-7004 / ENS-7002). This factory is purely an
+ * SDK-to-Enterstellar translator.
+ *
+ * @see Bible §4.15
+ * @see Design Choice AD3 — convention-based dot-notation for resource names
+ * @see Design Choice AD5 — error wrapping delegated to createDataAdapter()
+ */
+
+/**
+ * Creates a Firestore-backed `DataAdapter`.
+ *
+ * Maps Firestore SDK methods to the Enterstellar `DataAdapter` interface,
+ * then delegates to `createDataAdapter()` from `@enterstellar-ai/adapters`
+ * for config validation and AD5 error wrapping.
+ *
+ * @param config - Firestore data configuration with Firestore instance and optional overrides.
+ * @returns A frozen, validated `DataAdapter` instance.
+ * @throws `EnterstellarError` with code `ENS-7001` if config validation fails.
+ *
+ * @example
+ * ```ts
+ * import { initializeApp } from 'firebase/app';
+ * import { getFirestore } from 'firebase/firestore';
+ * import { createFirebaseDataAdapter } from '@enterstellar-ai/adapter-firebase';
+ *
+ * const app = initializeApp({ projectId: 'my-project', ... });
+ * const firestore = getFirestore(app);
+ * const data = createFirebaseDataAdapter({ firestore });
+ *
+ * // Query with filters
+ * const patients = await data.query('patients', { status: 'active' });
+ *
+ * // Mutate — create a document
+ * const newPatient = await data.mutate('patients', 'create', {
+ *   name: 'Jane Doe',
+ *   status: 'active',
+ * });
+ *
+ * // Subscribe to realtime changes
+ * const unsub = data.subscribe('patients', (records) => {
+ *   console.log('Patients updated:', records);
+ * });
+ * ```
+ */
+declare function createFirebaseDataAdapter(config: FirebaseDataConfig): DataAdapter;
+
+/**
+ * @module @enterstellar-ai/adapter-firebase/version
+ * @description Package version constant for `@enterstellar-ai/adapter-firebase`.
+ *
+ * Used by DevTools for version display and runtime compatibility checks.
+ * Must be kept in sync with the `version` field in `package.json`.
+ *
+ * @see Design Choice T14 — version exports
+ */
+/**
+ * Current version of the `@enterstellar-ai/adapter-firebase` package.
+ *
+ * @remarks
+ * This value MUST match the `version` field in `package.json`.
+ * Update this constant whenever a new version is released via Changesets.
+ */
+declare const FIREBASE_ADAPTER_VERSION: "0.0.0";
+
+export { FIREBASE_ADAPTER_VERSION, type FirebaseAuthConfig, type FirebaseDataConfig, createFirebaseAuthAdapter, createFirebaseDataAdapter };