@jobsearch-works/firestore-models 1.1.15 → 2.0.0

package/README.md

@@ -1,8 +1,10 @@
-# firestore-models
+# Firestore Models
 
 [![npm version](https://img.shields.io/npm/v/@jobsearch-works/firestore-models.svg?style=flat-square)](https://www.npmjs.com/package/@jobsearch-works/firestore-models)
 [![license](https://img.shields.io/npm/l/@jobsearch-works/firestore-models.svg?style=flat-square)](./LICENSE)
 
+Type-safe Firestore document models and path builders.
+
 A shared library for standardizing Firestore document schemas and paths across multiple projects.
 
 This library provides:
@@ -11,491 +13,202 @@ This library provides:
 - Pure Firestore path string builders (SDK-free)
 - Centralized schema definitions for use across apps
 
----
-
 ## 📦 Installation
 
 ```bash
 npm install @jobsearch-works/firestore-models
 ```
 
-For development:
-
-```bash
-npm install github:jobsearch-works/firestore-models
-```
-
-> ℹ️ Prefer the npm version for production. GitHub installs don't update via `npm update`.
-
----
-
-## 🎯 Purpose
+## Single Source of Truth
 
-This package acts as a single source of truth for Firestore schema and paths, enabling:
+This package is the single source of truth for:
 
-- 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)
+- Database paths (`@firestorePaths.ts`)
+- Document types (`@types`)
+- Static data (`@static`)
 
-This package provides no Firestore SDK bindings. Firestore `DocumentReference`s and `CollectionReference`s are constructed in your application using these path strings, typically in a `firestoreRefs.ts` file like:
+Example usage:
 
-```ts
-import { doc, collection } from "firebase/firestore";
-import { firestore } from "./firebaseConfig";
+```typescript
+// Paths (from @firestorePaths.ts)
 import { firestorePaths } from "@jobsearch-works/firestore-models";
-
-export const userRef = (userId: string) =>
-  doc(firestore, firestorePaths.users.doc(userId));
+const path = firestorePaths.clients.jobPreferences(
+  "hovdKgHzIDS7c8Kzt13QNG0xsEN2"
+);
+
+// Types (from @types)
+import { ClientJobPreferences } from "@jobsearch-works/firestore-models";
+const data: ClientJobPreferences = {
+  /* ... */
+};
+
+// Static data (from @static)
+import { locations } from "@jobsearch-works/firestore-models/static/locations";
+import jobClassifications from "@jobsearch-works/firestore-models/static/jobClassification";
 ```
 
----
+## Quick Start
 
-## 🧱 Project Structure
-
-```
-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
-```
-
----
-
-## 🔗 Entity Relationships
-
-The following diagram and table illustrate how the main Firestore models relate to each other, both by reference (IDs) and by Firestore subcollections/paths:
+```typescript
+import { firestorePaths } from "@jobsearch-works/firestore-models";
+import { doc, getDoc } from "firebase/firestore";
+import { firestore } from "./firebaseConfig";
 
+// Get a client's job preferences
+const clientId = "hovdKgHzIDS7c8Kzt13QNG0xsEN2"; // Real Firebase ID
+const path = firestorePaths.clients.jobPreferences(clientId);
+const ref = doc(firestore, path);
+const snap = await getDoc(ref);
+const data = { id: snap.id, ...snap.data() };
 ```
-Client
-  ├── applications (Application)
-  │     └── questions (ApplicationQuestion)
-  ├── questions (ClientQuestion)
-  ├── preferences/targetPreferences (TargetPreferences)
-  ├── vacancySuggestions (VacancySuggestion)
-  ├── emails (GmailMessage)
-  ├── logins (ClientLogin)
-  └── resumeLinks (ResumeLink)
-
-Vacancy
-  └── Referenced by Application and VacancySuggestion
-
-Agent
-  └── Root collection
-
-User
-  └── Root collection
-
-ClientData
-  └── Root collection
-```
-
-| Entity              | References / Path                                    | Description                                                          |
-| ------------------- | ---------------------------------------------------- | -------------------------------------------------------------------- |
-| Client              | Root collection                                      | Main user entity                                                     |
-| Application         | clients/{clientId}/applications/{applicationId}      | References `clientId`, `vacancyId`                                   |
-| ApplicationQuestion | .../applications/{applicationId}/questions/{qId}     | Subcollection of Application                                         |
-| ClientQuestion      | clients/{clientId}/questions/{questionId}            | Subcollection of Client                                              |
-| Vacancy             | Root collection                                      | Referenced by Application, VacancySuggestion                         |
-| VacancySuggestion   | clients/{clientId}/vacancySuggestions/{suggestionId} | References `clientId`, `vacancyId`                                   |
-| TargetPreferences   | clients/{clientId}/preferences/targetPreferences     | References `clientId`, contains `TargetJob[]` and `TargetLocation[]` |
-| TargetJob           | Embedded in TargetPreferences                        | Contains `category` (VacancyCategory)                                |
-| TargetLocation      | Embedded in TargetPreferences                        | List of preferred locations                                          |
-| Agent               | Root collection                                      | Standalone entity                                                    |
-| AuthUser            | Root collection                                      | Standalone entity                                                    |
-| ClientData          | Root collection                                      | Standalone entity                                                    |
-| ClientLogin         | clients/{clientId}/logins/{domain}                   | References `clientId`                                                |
-| GmailMessage        | clients/{clientId}/emails/{messageId}                | References `clientId`                                                |
-| ResumeLink          | clients/{clientId}/resumeLinks/{linkId}              | References `clientId`, stores PDF resume URLs                        |
 
-**Notes:**
+## Type Naming Convention
 
-- Most subcollections are nested under `Client` (e.g., applications, questions, vacancySuggestions).
-- `Application` and `VacancySuggestion` reference both `clientId` (parent) and `vacancyId` (target job).
-- `TargetPreferences` embeds arrays of `TargetJob` and `TargetLocation`.
-- All relationships are enforced by Firestore path structure and cross-referenced IDs.
+Types follow their Firestore paths. For example:
 
----
+- `clients/{id}/emailToken` → `ClientEmailToken`
+- `clients/{id}/jobPreferences` → `ClientJobPreferences`
+- `clients/{id}/personalData` → `ClientPersonalData`
 
-## ✅ Usage
+This makes it easy to find the right type for any path.
 
-This library is intentionally SDK-free. All Firebase logic — including `Timestamp`, `doc()`, and `onSnapshot()` — is handled in your app's service layer. This ensures portability across React apps, Firebase functions, and testing environments.
+## Type Casting Results
 
-### Importing Models and Paths
+```typescript
+import { ClientJobPreferences } from "@jobsearch-works/firestore-models";
+import { doc, getDoc } from "firebase/firestore";
 
-```ts
-import { Client } from "@jobsearch-works/firestore-models/types/Client";
-import { firestorePaths } from "@jobsearch-works/firestore-models/paths/firestorePaths";
+// 1. Get the document
+const path = firestorePaths.clients.jobPreferences(
+  "hovdKgHzIDS7c8Kzt13QNG0xsEN2"
+);
+const ref = doc(firestore, path);
+const snap = await getDoc(ref);
 
-const clientDocPath = firestorePaths.clients.doc("abc123"); // → "clients/abc123"
-```
+// 2. Cast the result (pick one method)
+const data = { id: snap.id, ...snap.data() } as ClientJobPreferences;
 
----
-
-## 📄 Firestore Models (Types)
-
-All Firestore document schemas are defined as TypeScript interfaces in `src/types`. These are pure data types (SDK-free) and can be reused across apps, functions, and tests.
-
-> **Why does every model include `id?: string`?**
-> Firestore's `.data()` does **not** include the document ID. This library's types include `id` as an optional property, which is added manually when fetching data. This makes it easier to use models in UI, caching, and linking between entities.
-
-### Main Types (alphabetical)
-
-- **Agent**
-
-  ```ts
-  export interface Agent {
-    id?: string;
-    name: string;
-    email: string;
-    status: "active" | "inactive";
-    profilePicture?: string;
-    createdAt?: Date | string;
-    updatedAt?: Date | string;
-  }
-  ```
-
-- **Application**
-
-  ```ts
-  export interface Application {
-    id?: string;
-    vacancyId: string;
-    clientId: string;
-    status: ApplicationStatus;
-    assignedTo?: string;
-    coverLetter?: string;
-    resume?: string;
-    // Status timestamps
-    submittedAt?: Date | string;
-    interviewingAt?: Date | string;
-    acceptedAt?: Date | string;
-    rejectedAt?: Date | string;
-    withdrawnAt?: Date | string;
-    applyingAt?: Date | string;
-    suggestedAt?: Date | string;
-    approvedAt?: Date | string;
-    // Denormalized/snapshot fields from Vacancy
-    company?: string;
-    position?: string;
-    location?: string;
-    jobId?: string;
-    advertisingUrl?: string;
-    applicationUrl?: string;
-    applicationDomain?: string;
-    advertisingDomain?: string;
-    description?: string;
-    fullPageText?: string;
-    createdAt?: Date | string;
-    updatedAt?: Date | string;
-  }
-  ```
-
-  - `ApplicationStatus` values: new, submitted, interviewing, accepted, rejected, withdrawn, applying, suggested, approved
-
-- **ApplicationQuestion**
-
-  ```ts
-  export interface ApplicationQuestion {
-    id?: string;
-    questionText: string;
-    answerText?: string;
-    type: "text" | "select";
-    createdAt?: Date | string;
-    updatedAt?: Date | string;
-  }
-  ```
-
-- **AuthUser**
-
-  ```ts
-  export interface AuthUser {
-    id?: string;
-    email: string;
-    displayName?: string;
-    photoURL?: string;
-    lastSignIn?: string; // ISO string
-    emailVerified?: boolean;
-    createdAt?: Date | string;
-    updatedAt?: Date | string;
-  }
-  ```
-
-- **Client**
-
-  ```ts
-  export interface Client {
-    id?: string;
-    name: string;
-    email: string;
-    status: "active" | "inactive";
-    resume?: string;
-    createdAt?: Date | string;
-  }
-  ```
-
-- **ClientData**
-
-  ```ts
-  export interface ClientData {
-    id?: string;
-    firstName: string;
-    lastName: string;
-    middleName?: string;
-    preferredName?: string;
-    email: string;
-    phone: string;
-    address: string;
-    city: string;
-    suburb: string;
-    state: string;
-    zip: string;
-    country: string;
-    linkedIn?: string;
-    countryPhoneCode: string;
-    nationality: string;
-    dateOfBirth?: Date | string;
-    createdAt?: Date | string;
-    updatedAt?: Date | string;
-  }
-  ```
-
-- **ClientLogin**
-
-  ```ts
-  export interface ClientLogin {
-    id?: string;
-    userId: string;
-    url: string;
-    domain: string;
-    username?: string;
-    password: string;
-    email?: string;
-    createdAt?: Date | string;
-    updatedAt?: Date | string;
-  }
-  ```
-
-- **ClientQuestion**
-
-  ```ts
-  export interface ClientQuestion {
-    id?: string;
-    questionText: string;
-    answerText?: string;
-    type: "text" | "select";
-    options?: string[];
-    createdAt?: Date | string;
-    updatedAt?: Date | string;
-  }
-  ```
-
-- **GmailMessage**
-
-  ```ts
-  export interface GmailMessage {
-    id?: string;
-  ```
-
-- **ResumeLink**
-
-  ```ts
-  export interface ResumeLink {
-    id?: string;
-    title: string;
-    url: string;
-    description: string;
-    createdAt?: Date | string;
-    createdBy: string;
-    clientId: string;
-  }
-  ```
-
-- **GmailMessage**
-
-  ```ts
-  export interface GmailMessage {
-    id?: string;
-    messageId: string;
-    threadId?: string;
-    labelIds?: string[];
-    snippet?: string;
-    internalDate?: string;
-    payload?: object;
-    createdAt?: Date | string;
-    updatedAt?: Date | string;
-  }
-  ```
-
-- **TargetJob**
-
-  ```ts
-  export interface TargetJob {
-    id?: string;
-    category: VacancyCategory;
-    position: string;
-    notes?: string;
-  }
-  ```
-
-- **TargetLocation**
-
-  ```ts
-  export interface TargetLocation {
-    id?: string;
-    country: string;
-    cities: {
-      name: string;
-      areas: string[];
-    }[];
-  }
-  ```
-
-- **TargetPreferences**
-
-  ```ts
-  export interface TargetPreferences {
-    id?: string;
-    clientId: string;
-    locations: TargetLocation[];
-    jobs: TargetJob[];
-    createdAt?: Date | string;
-    updatedAt?: Date | string;
-  }
-  ```
-
-- **Vacancy**
-
-  ```ts
-  export interface Vacancy {
-    id?: string;
-    company: string;
-    position: string;
-    location: string;
-    description: string;
-    advertisingUrl: string;
-    applicationUrl: string;
-    applicationDomain: string;
-    advertisingDomain: string;
-    fullPageText: string;
-    jobId: string;
-    category: VacancyCategory;
-    suggestedTo?: string[];
-    createdAt?: Date | string;
-    updatedAt?: Date | string;
-  }
-  ```
-
-  - `VacancyCategory` includes: Accounting, IT, Healthcare, Sales, etc.
-
-- **VacancySuggestion**
-  ```ts
-  export interface VacancySuggestion {
-    id?: string;
-    clientId: string;
-    vacancyId: string;
-    status: string;
-    createdAt?: Date | string;
-  }
-  ```
-
----
-
-## 🗂️ Firestore Path Utilities
-
-All Firestore collection/document path builders are centralized in `src/paths/firestorePaths.ts` as pure string helpers. **Every helper returns a Firestore path string, not a Firestore SDK reference.** This keeps the library SDK-free and fully portable for use in any environment (Node.js, browser, SSR, CLI, etc). No Firestore SDK is required or included.
-
-### Example Usage
-
-```ts
-import { firestorePaths } from "@jobsearch-works/firestore-models/paths/firestorePaths";
-
-const clientDoc = firestorePaths.clients.doc("clientId"); // "clients/clientId"
-const appDoc = firestorePaths.clients.applications.doc(
-  "clientId",
-  "applicationId"
-); // "clients/clientId/applications/applicationId"
-const vacancyDoc = firestorePaths.vacancies.doc("vacancyId"); // "vacancies/vacancyId"
+// OR use the helper function
+function withId<T>(snap: DocumentSnapshot): T & { id: string } {
+  return { id: snap.id, ...snap.data() } as T & { id: string };
+}
+const data = withId<ClientJobPreferences>(snap);
 ```
 
-#### Fetching a Firestore Document and Including Its ID
+## React + Zustand Example
 
-```ts
-import { doc, getDoc } from "firebase/firestore";
-import { firestore } from "../firebaseConfig";
+```typescript
+import { create } from "zustand";
+import { doc, onSnapshot } from "firebase/firestore";
 import { firestorePaths } from "@jobsearch-works/firestore-models";
+import { ClientJobPreferences } from "@jobsearch-works/firestore-models";
+
+// Store
+interface JobPreferencesStore {
+  preferences: ClientJobPreferences | null;
+  loading: boolean;
+  error: Error | null;
+  fetchPreferences: (clientId: string) => void;
+}
 
-const ref = doc(firestore, firestorePaths.vacancies.doc("vac123"));
-const snap = await getDoc(ref);
-const vacancy = { id: snap.id, ...snap.data() };
+export const useJobPreferences = create<JobPreferencesStore>((set) => ({
+  preferences: null,
+  loading: false,
+  error: null,
+  fetchPreferences: (clientId: string) => {
+    set({ loading: true });
+    const path = firestorePaths.clients.jobPreferences(clientId);
+    const ref = doc(firestore, path);
+
+    return onSnapshot(
+      ref,
+      (snap) => {
+        const data = { id: snap.id, ...snap.data() } as ClientJobPreferences;
+        set({ preferences: data, loading: false });
+      },
+      (error) => set({ error, loading: false })
+    );
+  },
+}));
+
+// Component
+function JobPreferences() {
+  const { preferences, loading, error, fetchPreferences } = useJobPreferences();
+  const clientId = "hovdKgHzIDS7c8Kzt13QNG0xsEN2";
+
+  useEffect(() => {
+    const unsubscribe = fetchPreferences(clientId);
+    return () => unsubscribe();
+  }, [clientId]);
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!preferences) return null;
+
+  return (
+    <div>
+      <h2>Job Preferences</h2>
+      <p>Desired Positions: {preferences.desiredPositions.join(", ")}</p>
+      <p>
+        Min Salary: {preferences.minSalary} {preferences.currency}
+      </p>
+    </div>
+  );
+}
 ```
 
-**Reusable withId Utility:**
+## Path Structure
 
-```ts
-export function withId<T>(snap: DocumentSnapshot): T & { id: string } {
-  return { id: snap.id, ...snap.data() } as T & { id: string };
-}
+```typescript
+// Collection paths
+firestorePaths.clients.collection(); // "clients"
+firestorePaths.clients.emails.collection("hovdKgHzIDS7c8Kzt13QNG0xsEN2"); // "clients/hovdKgHzIDS7c8Kzt13QNG0xsEN2/emails"
+
+// Document paths
+firestorePaths.clients.doc("hovdKgHzIDS7c8Kzt13QNG0xsEN2"); // "clients/hovdKgHzIDS7c8Kzt13QNG0xsEN2"
+firestorePaths.clients.personalData("hovdKgHzIDS7c8Kzt13QNG0xsEN2"); // "clients/hovdKgHzIDS7c8Kzt13QNG0xsEN2/personalData"
 ```
 
-#### Main Path Helpers
-
-- `firestorePaths.clients.collection()` → "clients"
-- `firestorePaths.clients.doc(clientId)` → "clients/{clientId}"
-- `firestorePaths.clients.applications.collection(clientId)` → "clients/{clientId}/applications"
-- `firestorePaths.clients.applications.doc(clientId, applicationId)` → "clients/{clientId}/applications/{applicationId}"
-- `firestorePaths.clients.applications.questions.collection(clientId, applicationId)` → "clients/{clientId}/applications/{applicationId}/questions"
-- `firestorePaths.clients.applications.questions.doc(clientId, applicationId, questionId)` → "clients/{clientId}/applications/{applicationId}/questions/{questionId}"
-- `firestorePaths.clients.emails.collection(clientId)` → "clients/{clientId}/emails"
-- `firestorePaths.clients.emails.doc(clientId, messageId)` → "clients/{clientId}/emails/{messageId}"
-- `firestorePaths.clients.logins.collection(clientId)` → "clients/{clientId}/logins"
-- `firestorePaths.clients.logins.doc(clientId, domain)` → "clients/{clientId}/logins/{domain}"
-- `firestorePaths.clients.preferences.target(clientId)` → "clients/{clientId}/preferences/targetPreferences"
-- `firestorePaths.clients.questions.collection(clientId)` → "clients/{clientId}/questions"
-- `firestorePaths.clients.questions.doc(clientId, questionId)` → "clients/{clientId}/questions/{questionId}"
-- `firestorePaths.clients.resumeLinks.collection(clientId)` → "clients/{clientId}/resumeLinks"
-- `firestorePaths.clients.resumeLinks.doc(clientId, resumeLinkId)` → "clients/{clientId}/resumeLinks/{resumeLinkId}"
-- `firestorePaths.clients.vacancySuggestions.collection(clientId)` → "clients/{clientId}/vacancySuggestions"
-- `firestorePaths.clients.vacancySuggestions.doc(clientId, suggestionId)` → "clients/{clientId}/vacancySuggestions/{suggestionId}"
-- `firestorePaths.users.collection()` → "users"
-- `firestorePaths.users.doc(userId)` → "users/{userId}"
-- `firestorePaths.vacancies.collection()` → "vacancies"
-- `firestorePaths.vacancies.doc(vacancyId)` → "vacancies/{vacancyId}"
-- `firestorePaths.agents.collection()` → "agents"
-- `firestorePaths.agents.doc(agentId)` → "agents/{agentId}"
-- `firestorePaths.clientData.collection()` → "clientData"
-- `firestorePaths.clientData.doc(clientDataId)` → "clientData/{clientDataId}"
-
----
-
-## 🛡️ Notes
-
-- All types and paths are SDK-independent and safe to use in any TypeScript/Node/React project.
-- This package does not include any Firestore SDK or database logic—just models and helpers.
-- For Firestore access, use your own service layer or SDK wrapper.
-- This library follows semantic versioning and is safe for production use.
-
----
-
-## 🔗 Path Builder Example
-
-```ts
-// paths/pathStrings.ts
-export const pathStrings = {
-  clients: () => "clients",
-  client: (clientId: string) => `clients/${clientId}`,
-} as const;
+## Type Safety
+
+```typescript
+import {
+  ClientJobPreferences,
+  JobCategory,
+  JobTitle,
+  LocationId,
+} from "@jobsearch-works/firestore-models";
+
+// Type-safe job preferences
+const preferences: ClientJobPreferences = {
+  clientId: "hovdKgHzIDS7c8Kzt13QNG0xsEN2",
+  desiredPositions: ["Software Engineering"], // TypeScript autocomplete
+  categories: ["Information & Communication Technology"], // TypeScript autocomplete
+  locations: ["sydney", "london"], // TypeScript autocomplete
+  minSalary: 100000,
+  currency: "AUD",
+  industries: ["Technology"],
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
 ```
 
----
+## Static Data
+
+```typescript
+import jobClassifications from "@jobsearch-works/firestore-models/static/jobClassification";
+import { locations } from "@jobsearch-works/firestore-models/static/locations";
 
-## 🧩 Contributing
+// Job categories and titles
+type JobCategory = keyof typeof jobClassifications;
+type JobTitle = (typeof jobClassifications)[JobCategory][number];
 
-When adding a new model:
+// Location IDs
+type LocationId = (typeof locations)[number]["id"];
+```
+
+## Installation
 
-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
+```bash
+npm install @jobsearch-works/firestore-models
+```