@jobsearch-works/firestore-models 1.0.33 → 1.1.0

package/README.md

@@ -1,332 +1,106 @@
 # firestore-models
 
-A shared library for standardizing Firestore document schemas and paths across multiple projects. This library provides:
+A shared library for standardizing Firestore document schemas and paths across multiple projects.
 
-- Standardized document models and interfaces
-- Consistent path builders for Firestore collections and documents
-- Type-safe access to Firestore data
-- Shared validation and transformation utilities
+This library provides:
 
-## Purpose
+- Type-safe Firestore document models
+- Pure Firestore path string builders (SDK-free)
+- Centralized schema definitions for use across apps
 
-This library serves as a single source of truth for Firestore data structures across different applications. By centralizing the schema definitions, it:
+---
 
-- Ensures consistency in data structure across projects
-- Reduces duplication of model definitions
-- Provides type safety when working with Firestore data
-- Makes it easier to maintain and update schemas across all applications
-
-## Installation
-
-The package is published on npm as [@jobsearch-works/firestore-models](https://www.npmjs.com/package/@jobsearch-works/firestore-models).
-
-You can install it using npm:
+## 📦 Installation
 
 ```bash
 npm install @jobsearch-works/firestore-models
 ```
 
-For development purposes, you can also install directly from GitHub:
+For development:
 
 ```bash
-# Install from GitHub (for development only)
 npm install github:jobsearch-works/firestore-models
-
-# Or specify a particular commit/branch
-npm install github:jobsearch-works/firestore-models#commit-hash
-```
-
-Note: Regular `npm update` won't update GitHub-hosted packages to the latest version. For production use, always use the npm package version.
-
-## Project Structure
-
-```
-firestore-models/
-├── src/
-│   ├── models/           # All Firestore models
-│   │   ├── Application.ts
-│   │   ├── AuthUser.ts
-│   │   ├── Client.ts
-│   │   ├── ClientData.ts
-│   │   ├── ClientLogin.ts
-│   │   ├── Question.ts
-│   │   ├── UserQuestion.ts
-│   │   ├── Vacancy.ts
-│   │   └── VacancySuggestion.ts
-│   ├── BaseModel.ts      # Base interface for all models
-│   └── index.ts          # Main entry point
-├── dist/                 # Compiled output
-└── package.json
 ```
 
-## Base Model
+> ℹ️ Prefer the npm version for production. GitHub installs don't update via `npm update`.
 
-All models extend from the BaseModel interface:
+---
 
-```typescript
-interface BaseModel {
-  id?: string; // Optional document ID
-  createdAt?: Date | string; // Optional creation timestamp
-  updatedAt?: Date | string; // Optional update timestamp
-}
-```
-
-## Models and Namespaces
-
-Each model is defined within its own namespace, which includes:
-
-- The model interface
-- Path builders for Firestore collections and documents
-- Utility functions for working with the model
-
-### Client
+## 🎯 Purpose
 
-```typescript
-namespace Client {
-  interface Model extends BaseModel {
-    name: string;
-    email: string;
-    status: "active" | "inactive";
-    resume?: string;
-  }
+This package acts as a single source of truth for Firestore schema and paths, enabling:
 
-  // Path builders
-  const collection = () => "clients";
-  const document = (clientId: string) => `clients/${clientId}`;
+- Shared types across web apps, Node services, and Firebase functions
+- Consistent Firestore path generation (no hardcoded strings)
+- Cross-environment compatibility (e.g., CLI, testing, rules)
 
-  // Utility functions
-  const formatClient = (client: Client.Model): string;
-  const createNew = (name: string, email: string): Client.Model;
-}
-```
+---
 
-### Application
-
-```typescript
-namespace Application {
-  interface Model extends BaseModel {
-    vacancyId: string;
-    clientId: string;
-    status:
-      | "new"
-      | "submitted"
-      | "interviewing"
-      | "accepted"
-      | "rejected"
-      | "withdrawn"
-      | "applying"
-      | "suggested"
-      | "approved";
-    coverLetter?: string;
-    resume?: string;
-    // Denormalized fields from Vacancy
-    company?: string;
-    position?: string;
-    location?: string;
-    jobId?: string;
-    advertisingUrl?: string;
-    applicationUrl?: string;
-    applicationDomain?: string;
-    advertisingDomain?: string;
-    description?: string;
-    fullPageText?: string;
-  }
-
-  // Path builders
-  const collection = (clientId: string) => `clients/${clientId}/applications`;
-  const document = (clientId: string, applicationId: string) =>
-    `clients/${clientId}/applications/${applicationId}`;
-
-  // Utility functions
-  const formatSummary = (application: Application.Model): string;
-  const formatDate = (date: Date | string): string;
-  const createNew = (
-    clientId: string,
-    vacancyId: string,
-    vacancyData: Partial<Vacancy.Model>
-  ): Application.Model;
-  const updateStatus = (
-    application: Application.Model,
-    newStatus: Application.Model["status"]
-  ): Application.Model;
-}
-```
+## 🧱 Project Structure
 
-### AuthUser
-
-```typescript
-namespace AuthUser {
-  interface Model extends BaseModel {
-    email: string;
-    displayName?: string;
-    photoURL?: string;
-    lastSignIn?: Date | string;
-    emailVerified?: boolean;
-  }
-
-  // Path builders
-  const collection = () => "users";
-  const document = (userId: string) => `users/${userId}`;
-
-  // Utility functions
-  const fromFirebaseUser = (user: any): AuthUser.Model;
-  const formatDates = (user: AuthUser.Model): Record<string, string>;
-  const toFirestore = (user: AuthUser.Model): Record<string, any>;
-  const fromFirestore = (data: Record<string, any>): AuthUser.Model;
-}
 ```
-
-### Vacancy
-
-```typescript
-namespace Vacancy {
-  interface Model extends BaseModel {
-    company: string;
-    position: string;
-    location: string;
-    jobId: string;
-    advertisingUrl: string;
-    applicationUrl: string;
-    applicationDomain: string;
-    advertisingDomain: string;
-    description: string;
-    fullPageText: string;
-    status: "active" | "inactive";
-  }
-
-  // Path builders
-  const collection = () => "vacancies";
-  const document = (vacancyId: string) => `vacancies/${vacancyId}`;
-}
-```
-
-### Question
-
-```typescript
-namespace Question {
-  interface Model extends BaseModel {
-    text: string;
-    type: "text" | "multiple_choice" | "single_choice";
-    options?: string[];
-    required: boolean;
-    order: number;
-  }
-
-  // Path builders
-  const collection = () => "questions";
-  const document = (questionId: string) => `questions/${questionId}`;
-}
+firestore-models/
+├── src/
+│   ├── types/              # Pure Firestore interfaces (SDK-free)
+│   ├── paths/              # Pure path string builders (SDK-free)
+│   └── index.ts            # Main exports (types + paths only)
+├── dist/                   # Compiled output
+└── package.json
 ```
 
-### UserQuestion
-
-```typescript
-namespace UserQuestion {
-  interface Model extends BaseModel {
-    clientId: string;
-    questionId: string;
-    answer: string;
-  }
+---
 
-  // Path builders
-  const collection = (clientId: string) => `clients/${clientId}/questions`;
-  const document = (clientId: string, questionId: string) =>
-    `clients/${clientId}/questions/${questionId}`;
-}
-```
+## ✅ Usage
 
-### ClientData
+### Importing Models and Paths
 
-```typescript
-namespace ClientData {
-  interface Model extends BaseModel {
-    clientId: string;
-    key: string;
-    value: any;
-  }
+```ts
+import { Client } from "@jobsearch-works/firestore-models/types/Client";
+import { pathStrings } from "@jobsearch-works/firestore-models/paths/pathStrings";
 
-  // Path builders
-  const collection = (clientId: string) => `clients/${clientId}/data`;
-  const document = (clientId: string, key: string) =>
-    `clients/${clientId}/data/${key}`;
-}
+const clientPath = pathStrings.client("abc123"); // → "clients/abc123"
 ```
 
-### ClientLogin
+---
 
-```typescript
-namespace ClientLogin {
-  interface Model extends BaseModel {
-    clientId: string;
-    ipAddress: string;
-    userAgent: string;
-  }
+## 🔒 Type Definition Example
 
-  // Path builders
-  const collection = (clientId: string) => `clients/${clientId}/logins`;
-  const document = (clientId: string, loginId: string) =>
-    `clients/${clientId}/logins/${loginId}`;
+```ts
+// types/Client.ts
+export interface Client {
+  id?: string;
+  name: string;
+  email: string;
+  status: "active" | "inactive";
+  createdAt?: Date | string;
 }
 ```
 
-### VacancySuggestion
+---
 
-```typescript
-namespace VacancySuggestion {
-  interface Model extends BaseModel {
-    clientId: string;
-    vacancyId: string;
-    status: "pending" | "accepted" | "rejected";
-  }
+## 🔗 Path Builder Example
 
-  // Path builders
-  const collection = (clientId: string) => `clients/${clientId}/suggestions`;
-  const document = (clientId: string, suggestionId: string) =>
-    `clients/${clientId}/suggestions/${suggestionId}`;
-}
+```ts
+// paths/pathStrings.ts
+export const pathStrings = {
+  clients: () => "clients",
+  client: (clientId: string) => `clients/${clientId}`,
+} as const;
 ```
 
-## Services
+---
 
-For data access, use the provided services instead of directly accessing Firestore. Services provide a consistent interface for data operations and handle error cases.
-
-### ClientDataService
-
-```typescript
-import { ClientDataService } from "@jobsearch-works/services";
-
-// Get client data
-const clientData = await ClientDataService.getData(userId);
-```
-
-## Usage
-
-Import the models and services in your application:
-
-```typescript
-import { Client } from "@jsw/firestore-models";
-import { ClientDataService } from "@jobsearch-works/services";
-
-// Create a new client
-const newClient = Client.createNew("John Doe", "john@example.com");
-
-// Use services for data access
-const clientData = await ClientDataService.getData("123");
-
-// Use the utility functions
-const formattedClient = Client.formatClient(newClient);
-```
+## 🧩 Contributing
 
-## Contributing
+When adding a new model:
 
-When adding new models or modifying existing ones:
+1. Add its interface under `src/types/`
+2. Add its path builder in `src/paths/pathStrings.ts`
+3. Update the documentation if needed
+4. Maintain backward compatibility
 
-1. Update the TypeScript interfaces
-2. Add corresponding path builders
-3. Update any validation or transformation utilities
-4. Update this documentation
-5. Ensure backward compatibility when possible
+---
 
-## License
+## 📄 License
 
 MIT