@donotdev/firebase 0.0.1

package/LICENSE.md

@@ -0,0 +1,242 @@
+# DoNotDev Framework License Agreement
+
+**Version 1.0 – Effective Date: May 5, 2025**
+
+Copyright © 2025 Ambroise Park Consulting. All rights reserved.
+
+---
+
+## 1. DEFINITIONS
+
+**1.1 "Framework"** means the DoNotDev commercial software packages (excluding @donotdev/cli and @donotdev/components, which are free), including all compiled JavaScript files, TypeScript definition files, and associated documentation.
+
+**1.2 "License Key"** means the unique alphanumeric key provided to you upon purchase, required to suppress watermarks and unlock full Framework functionality.
+
+**1.3 "Developer License"** means a license granted to an individual developer, permitting use of the Framework subject to the terms herein.
+
+**1.4 "Project Deployment License"** means a license required for each Client Project delivered by a Developer.
+
+**1.5 "Client Project"** means any software application or website built using the Framework and delivered to a third party who compensated you (directly or indirectly) for its development. This includes:
+- Code handoff (repository transfer, zip file delivery, etc.)
+- Hosted applications where the client has access to source code (repository access, cPanel, FTP, etc.)
+- Hosted applications operated on behalf of a paying client, regardless of code access
+
+**1.6 "Internal Use"** means software applications built using the Framework for your own use or your employer's internal use, including SaaS products you own and operate where end-users have no access to Framework code.
+
+---
+
+## 2. LICENSE GRANT
+
+**2.1 Developer License**
+
+Subject to payment of applicable fees and compliance with this Agreement, Ambroise Park Consulting grants you a non-exclusive, non-transferable, perpetual license to:
+
+(a) Install Framework packages from npm
+(b) Use the Framework to develop software applications
+(c) Deploy applications for Internal Use without additional fees
+(d) Incorporate the Framework into applications as compiled/minified code
+
+**2.2 Project Deployment License**
+
+For each Client Project, you must obtain a Project Deployment License prior to delivery. Each Project Deployment License grants you the right to deliver one Client Project containing the Framework.
+
+**2.3 Multi-Developer Projects**
+
+When multiple developers collaborate on a project:
+- Each developer must hold a Developer License with their own License Key
+- Only one Project Deployment License is required per Client Project (regardless of team size)
+
+---
+
+## 3. LICENSE KEY REQUIREMENT
+
+**3.1 License Key Activation**
+
+Upon purchasing a Developer License or Project Deployment License, you will receive a License Key. You must configure your applications with this key:
+
+```javascript
+// Environment variable (recommended)
+DONOTDEV_LICENSE_KEY=your-license-key-here
+
+// Or in code
+globalThis.__DONOTDEV_LICENSE_KEY__ = 'your-license-key-here';
+```
+
+**3.2 Watermark Enforcement**
+
+Applications running without a valid License Key will display a watermark:
+- "⚠️ Unlicensed DoNotDev Framework - Visit donotdev.com"
+- Console warnings in development mode
+
+**3.3 License Key Types**
+
+- **Developer License Key:** For Internal Use and development
+- **Project Deployment License Key:** For Client Project deployment (suppresses watermark in production)
+
+**3.4 Key Management**
+
+- Do not commit License Keys to public repositories
+- Use environment variables or secure secret management for production deployments
+- Each developer uses their own Developer License Key for development
+- Project Deployment Keys are provisioned per client project
+
+---
+
+## 4. PERMITTED USES
+
+You may:
+
+(a) Build unlimited applications for Internal Use with a Developer License
+(b) Develop SaaS products you own and operate (no Project Deployment License required if clients cannot access Framework code)
+(c) Create internal tools for your organization
+(d) Build applications that include the Framework as compiled dependencies
+(e) Open-source applications built on top of the Framework (provided end-users obtain their own licenses to suppress watermarks)
+
+---
+
+## 5. RESTRICTIONS
+
+You may not:
+
+(a) Redistribute Framework packages independently of your applications
+(b) Share, publish, or transfer your License Key to unlicensed parties
+(c) Decompile, reverse engineer, or attempt to extract source code from minified files
+(d) Remove or obscure copyright notices or watermarks from Framework code
+(e) Sublicense, resell, or transfer your Developer License to another individual
+(f) Deliver Client Projects without obtaining a Project Deployment License
+(g) Modify Framework code to bypass license validation or watermark enforcement
+(h) Create derivative frameworks intended for redistribution
+(i) Use a single Project Deployment License for multiple client projects
+
+---
+
+## 6. LICENSE TYPES & FEES
+
+**6.1 Developer License**
+- **Scope:** Per individual developer
+- **Term:** Perpetual (lifetime access)
+- **Fee:** Set forth in purchase agreement or donotdev.com pricing
+- **Entitlements:** Unlimited Internal Use projects; Client Projects require additional Project Deployment Licenses
+- **License Key:** One Developer License Key provided
+
+**6.2 Project Deployment License**
+- **Scope:** Per Client Project delivered
+- **Term:** Perpetual for the specific project
+- **Fee:** Set forth in purchase agreement or donotdev.com pricing
+- **Purchaser:** Typically purchased by the developer/agency; client payment arrangements are permitted
+- **License Key:** One Project Deployment Key provided per project
+
+**6.3 Volume Licensing**
+
+Organizations requiring multiple Developer Licenses may contact Ambroise Park Consulting for volume pricing and enterprise key management.
+
+---
+
+## 7. PAYMENT & VERIFICATION
+
+**7.1 Payment**
+
+All fees must be paid in full before License Key issuance. Payment terms and pricing are specified at donotdev.com or in separate purchase agreements.
+
+**7.2 Compliance Verification**
+
+Ambroise Park Consulting may request reasonable verification of Project Deployment License compliance. You agree to cooperate with such verification requests in good faith.
+
+**7.3 Enforcement**
+
+License compliance is primarily honor-based. Watermarks serve as technical reminders. Ambroise Park Consulting reserves the right to audit usage and pursue legal remedies for material breaches.
+
+---
+
+## 8. TERM & TERMINATION
+
+**8.1 Perpetual Term**
+
+Developer Licenses and Project Deployment Licenses are perpetual and do not expire, subject to Section 8.2.
+
+**8.2 Termination for Breach**
+
+Ambroise Park Consulting may terminate your license(s) and revoke your License Key(s) if you:
+- Breach any material term of this Agreement
+- Fail to pay applicable fees
+- Engage in unauthorized redistribution or License Key sharing
+- Attempt to bypass license validation mechanisms
+
+**8.3 Effect of Termination**
+
+Upon termination:
+- Your License Key(s) will be revoked and watermarks will reappear
+- Your right to use the Framework ceases
+- Previously deployed applications may continue to function but will display watermarks
+- You must cease distribution of any Client Projects in development
+- You must remove the Framework from any ongoing projects
+
+**8.4 Survival**
+
+Sections 5 (Restrictions), 9 (Warranty Disclaimer), 10 (Limitation of Liability), and 11 (General Provisions) survive termination.
+
+---
+
+## 9. WARRANTY DISCLAIMER
+
+THE FRAMEWORK IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+
+Ambroise Park Consulting does not warrant that the Framework will be error-free, uninterrupted, or meet your specific requirements.
+
+---
+
+## 10. LIMITATION OF LIABILITY
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL AMBROISE PARK CONSULTING BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES (INCLUDING LOSS OF PROFITS, DATA, OR BUSINESS OPPORTUNITIES) ARISING OUT OF OR RELATED TO THIS AGREEMENT OR USE OF THE FRAMEWORK, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+Ambroise Park Consulting's total cumulative liability under this Agreement shall not exceed the fees you paid for the specific license giving rise to the claim.
+
+---
+
+## 11. GENERAL PROVISIONS
+
+**11.1 Governing Law**
+
+This Agreement is governed by the laws of Quebec, Canada, without regard to conflict of law principles. Any disputes arising under this Agreement shall be resolved exclusively in the courts of Quebec, Canada.
+
+**11.2 Severability**
+
+If any provision of this Agreement is found unenforceable, the remaining provisions continue in full force and effect.
+
+**11.3 Assignment**
+
+You may not assign or transfer this Agreement or any licenses granted hereunder without prior written consent of Ambroise Park Consulting. Ambroise Park Consulting may assign this Agreement without restriction.
+
+**11.4 Entire Agreement**
+
+This Agreement, together with any applicable purchase agreements or order forms, constitutes the entire agreement between you and Ambroise Park Consulting regarding the Framework and supersedes all prior agreements and understandings.
+
+**11.5 Amendments**
+
+Ambroise Park Consulting may update this Agreement from time to time. Updates apply to licenses purchased after the effective date of the update. Existing licenses remain governed by the version in effect at the time of purchase unless you opt-in to updated terms.
+
+**11.6 Export Compliance**
+
+You agree to comply with all applicable export and import laws and regulations in your use of the Framework.
+
+**11.7 Force Majeure**
+
+Neither party is liable for failure to perform due to causes beyond reasonable control, including but not limited to acts of God, war, strikes, or third-party service outages.
+
+**11.8 No Support Obligation**
+
+Ambroise Park Consulting has no obligation to provide support, updates, or maintenance. Any support provided is at sole discretion and may be discontinued without notice.
+
+**11.9 Contact**
+
+Questions about licensing or compliance:
+
+**Email:** mooti.web.app@gmail.com
+**Website:** donotdev.com
+
+---
+
+**END OF LICENSE AGREEMENT**
+
+**DoNotDev Framework License v2.0**
+Ambroise Park Consulting – 2025

package/README.md

@@ -0,0 +1,386 @@
+# @donotdev/firebase
+
+Firebase utilities for DoNotDev applications. This package provides a clean separation between client-safe and server-only Firebase functions.
+
+## Structure
+
+This package is split into two main parts:
+
+### Client-Safe Exports (Default)
+
+Import from the main package for client-safe functions:
+
+```typescript
+import { initFirebase, getAuth } from '@donotdev/firebase';
+import { getFirestore } from '@donotdev/firebase/server';
+```
+
+**Available modules:**
+
+- `auth.ts` - Authentication utilities
+- `init.ts` - Firebase initialization
+- `transform.ts` - Data transformation utilities
+- `utils.ts` - Client-safe utility functions
+- `validation.ts` - Client-safe validation functions
+- `uniqueness.ts` - Uniqueness validation (client-safe functions only)
+
+### Server-Only Exports
+
+Import from the server subpath for server-only functions:
+
+```typescript
+import { batchWrite, getActiveSubscription } from '@donotdev/firebase/server';
+```
+
+**Available modules:**
+
+- `batch.ts` - Batch operations (create, update, delete)
+- `subscription.ts` - Subscription management
+- `server/utils.ts` - Server-only utilities
+- `validation.ts` - Server-only validation functions
+- `uniqueness.ts` - Server-only uniqueness functions
+
+## Features
+
+- **Data Transformation**: Convert between Firestore and application formats
+- **Uniqueness Validation**: Enforce field uniqueness constraints
+- **Schema Validation**: Validate documents against schemas
+- **Batch Operations**: Efficiently handle multiple document operations
+- **Authentication**: Type-safe auth utilities with standard error handling
+- **Initialization**: Simple configuration with environment variable support
+
+## Installation
+
+```bash
+bun add @donotdev/firebase
+```
+
+## Usage Examples
+
+### Client-Side (Browser/SSR)
+
+```typescript
+import { initFirebase, getAuth } from '@donotdev/firebase';
+
+// Initialize Firebase
+const { app, auth } = initFirebase();
+
+// Use client SDK
+const user = auth?.currentUser;
+```
+
+### Server-Side (API Routes, Server Actions)
+
+```typescript
+import { batchWrite, getActiveSubscription } from '@donotdev/firebase/server';
+
+// Batch operations
+const result = await batchWrite('users', users, 'create');
+
+// Subscription management
+const subscription = await getActiveSubscription(userId);
+```
+
+### Data Transformation
+
+```typescript
+import {
+  transformFirestoreData,
+  prepareForFirestore,
+} from '@donotdev/firebase';
+
+// Convert Firestore Timestamps to ISO strings
+const appData = transformFirestoreData(firestoreData);
+
+// Convert ISO strings to Firestore Timestamps
+const firestoreData = prepareForFirestore(appData);
+```
+
+### Schema Validation
+
+```typescript
+import { enhanceSchema, validateCreate } from '@donotdev/firebase';
+import * as v from 'valibot';
+
+// Create a schema with uniqueness constraints
+const userSchema = enhanceSchema(
+  v.object({
+    email: z.string().email(),
+    username: z.string().min(3),
+    createdAt: z.string().datetime(),
+  }),
+  {
+    collection: 'users',
+    uniqueFields: [
+      { field: 'email', errorMessage: 'Email is already in use' },
+      { field: 'username', errorMessage: 'Username is taken' },
+    ],
+  }
+);
+
+// Validate a document before saving
+try {
+  await validateCreate(userSchema, userData);
+  // Document is valid, proceed with saving
+} catch (error) {
+  // Handle validation errors
+  console.error('Validation failed:', error);
+}
+```
+
+### Batch Operations
+
+```typescript
+import { batchCreate, batchUpdate, batchDelete } from '@donotdev/firebase';
+
+// Create multiple documents
+const createResult = await batchCreate('products', products);
+console.log(
+  `Created ${createResult.successes} products with ${createResult.failures} failures`
+);
+
+// Update multiple documents
+const updateResult = await batchUpdate('products', updatedProducts);
+
+// Delete multiple documents
+const deleteResult = await batchDelete('products', productIds, {
+  idField: 'id',
+});
+```
+
+### Authentication
+
+The Firebase SDK automatically handles `authDomain` configuration using a dynamic approach:
+
+- **Client-Side (CSR)**: Uses `window.location.hostname` for same-origin authentication
+- **Server-Side (SSR)**: Uses `APP_URL` environment variable hostname
+- **Localhost**: Falls back to `${projectId}.firebaseapp.com` for Firebase infrastructure
+
+No manual `authDomain` configuration required - the SDK handles this automatically.
+
+```typescript
+import {
+  signInWithEmail,
+  signInWithGoogle,
+  getCurrentUser,
+  signOut,
+  getIdToken,
+} from '@donotdev/firebase';
+
+// Sign in with email/password
+const user = await signInWithEmail('user@example.com', 'password');
+
+// Sign in with Google
+const user = await signInWithGoogle();
+
+// Get current user
+const currentUser = getCurrentUser();
+
+// Get authentication token
+const token = await getIdToken();
+
+// Sign out
+await signOut();
+```
+
+### Initialization
+
+```typescript
+import { initFirebase } from '@donotdev/firebase';
+
+// Initialize Firebase from environment variables
+const { app, auth, firestore } = initFirebase();
+
+// Or with custom configuration
+const { app, auth, firestore } = initFirebase({
+  apiKey: 'your-api-key',
+  authDomain: 'your-project.firebaseapp.com',
+  projectId: 'your-project-id',
+  // ...other config
+});
+
+// Use emulators for development
+const { app, auth, firestore } = initFirebase(undefined, true);
+```
+
+## Key Benefits
+
+1. **No Client Bundling Issues**: Server-only functions are never bundled in client builds
+2. **Clear Separation**: Easy to understand what's safe for client vs server
+3. **Type Safety**: Full TypeScript support for both client and server functions
+4. **Framework Agnostic**: Works with Next.js, Vite, and other frameworks
+
+## Migration Guide
+
+If you were previously importing server functions from the main package:
+
+**Before:**
+
+```typescript
+import { batchWrite } from '@donotdev/firebase';
+```
+
+**After:**
+
+```typescript
+import { batchWrite } from '@donotdev/firebase/server';
+```
+
+## Environment Variables
+
+Required for client initialization:
+
+- `VITE_FIREBASE_API_KEY`
+- `VITE_FIREBASE_PROJECT_ID`
+
+Optional:
+
+- `VITE_FIREBASE_STORAGE_BUCKET`
+- `VITE_FIREBASE_MESSAGING_SENDER_ID`
+- `VITE_FIREBASE_APP_ID`
+- `VITE_FIREBASE_MEASUREMENT_ID`
+
+## Demo Mode
+
+The package includes a demo mode that activates when Firebase configuration is missing. This allows development without Firebase setup.
+
+```typescript
+import { isFirebaseDemoMode } from '@donotdev/firebase';
+
+if (isFirebaseDemoMode()) {
+  console.log('Running in demo mode');
+}
+```
+
+## Integration with DoNotDev
+
+This package integrates seamlessly with other DoNotDev packages:
+
+- Use with `@donotdev/schemas` for complete entity validation
+- Pair with `@donotdev/hooks` for type-safe data access
+- Works with `@donotdev/auth` for comprehensive authentication
+
+## Core Modules
+
+### transform.ts
+
+Data transformation utilities for converting between Firestore and application formats.
+
+- `transformFirestoreData`: Converts Timestamps to ISO strings
+- `prepareForFirestore`: Converts ISO strings to Timestamps
+- `toTimestamp`: Converts Date or ISO string to Firestore Timestamp
+- `toISOString`: Converts DateValue to ISO string
+- `createFirestorePartialUpdate`: Creates a diff for partial updates
+
+### validation.ts
+
+Document validation against schemas with uniqueness constraints.
+
+- `validateFirestoreDocument`: Validates document against schema and checks uniqueness
+- `validateCreate`: Validates document for creation
+- `validateUpdate`: Validates document for update
+- `enhanceSchema`: Adds Firestore metadata to schema
+
+### uniqueness.ts
+
+Uniqueness constraint validation to ensure field values are unique.
+
+- `validateUniqueness`: Validates uniqueness constraints for a document
+- `createFirestoreValidator`: Server-side validator for uniqueness
+- `createFirestoreClientValidator`: Client-side validator for uniqueness
+
+### batch.ts
+
+Utilities for batch operations with automatic chunking.
+
+- `batchWrite`: Generic batch write operation
+- `batchCreate`: Creates multiple documents
+- `batchUpdate`: Updates multiple documents
+- `batchDelete`: Deletes multiple documents
+- `bulkGet`: Fetches multiple documents by ID
+
+### auth.ts
+
+Authentication utilities for client-side operations.
+
+- `signInWithEmail`: Signs in with email and password
+- `signInWithGoogle`: Signs in with Google
+- `resetPassword`: Sends password reset email
+- `getCurrentUser`: Gets current authenticated user
+- `getIdToken`: Gets authentication token
+- `signOut`: Signs out current user
+- `isCurrentUserAdmin`: Checks if current user has admin role
+
+### utils.ts
+
+Core utilities for Firebase operations.
+
+- `handleFirebaseError`: Standardizes Firebase errors
+- `generateId`: Generates unique IDs for documents
+- `executeFirebaseOperation`: Executes operation with retry support
+
+### init.ts
+
+Initialization utilities for Firebase in different environments.
+
+- `initFirebase`: Initializes Firebase from environment variables or config
+- `initAdminApp`: Initializes Firebase Admin SDK
+
+## Best Practices
+
+1. Always transform data when crossing the Firebase boundary:
+
+   ```typescript
+   // Before saving to Firestore
+   const firestoreData = prepareForFirestore(appData);
+
+   // After fetching from Firestore
+   const appData = transformFirestoreData(firestoreData);
+   ```
+
+2. Use batch operations for multiple documents:
+
+   ```typescript
+   // Instead of multiple individual writes
+   await batchCreate('products', newProducts);
+   ```
+
+3. Handle errors consistently:
+
+   ```typescript
+   try {
+     // Firebase operation
+   } catch (error) {
+     throw handleFirebaseError(error, 'Operation name');
+   }
+   ```
+
+4. Enforce uniqueness constraints:
+
+   ```typescript
+   const schema = enhanceSchema(productSchema, {
+     collection: 'products',
+     uniqueFields: [{ field: 'sku', errorMessage: 'SKU already exists' }],
+   });
+   ```
+
+5. For server environments, initialize validator early:
+
+   ```typescript
+   import { createFirestoreValidator } from '@donotdev/firebase/server';
+
+   async function initializeApp() {
+     // Set up validator once at app startup
+     await createFirestoreValidator();
+   }
+   ```
+
+## 📄 License & Ownership
+
+All rights reserved.  
+The DoNotDev framework and its premium features are the exclusive property of **Ambroise Park Consulting**.
+
+- Premium features require an active paid subscription.
+- Redistribution, reverse-engineering, or commercial reuse is strictly prohibited without written authorization.
+
+© Ambroise Park Consulting – 2025