@jobsearch-works/firestore-models 1.0.0

package/README.md

@@ -0,0 +1,57 @@
+# firestore-models
+
+A shared library for standardizing Firestore document schemas and paths across multiple projects. This library provides:
+
+- Standardized document models and interfaces
+- Consistent path builders for Firestore collections and documents
+- Type-safe access to Firestore data
+- Shared validation and transformation utilities
+
+## Purpose
+
+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
+
+```bash
+npm install @jsw/firestore-models
+# or
+yarn add @jsw/firestore-models
+```
+
+## Usage
+
+Import the models and path builders in your application:
+
+```typescript
+import { User, userPath } from "@jsw/firestore-models";
+
+// Use the type-safe model
+const user: User = {
+  id: "123",
+  name: "John Doe",
+  email: "john@example.com",
+};
+
+// Use the path builder
+const userDocPath = userPath("123"); // returns 'users/123'
+```
+
+## Contributing
+
+When adding new models or modifying existing ones:
+
+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
+
+MIT

package/dist/BaseModel.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Generic type for all model interfaces
+ */
+export interface BaseModel {
+    id?: string;
+    createdAt?: Date | string;
+    updatedAt?: Date | string;
+}

package/dist/BaseModel.js

@@ -0,0 +1 @@
+export {};

package/dist/models/VacancySuggestion.d.ts

@@ -0,0 +1,19 @@
+import { BaseModel } from "../BaseModel";
+export declare namespace VacancySuggestion {
+    /**
+     * Represents a job vacancy suggestion for a client
+     */
+    interface Model extends BaseModel {
+        clientId: string;
+        vacancyId: string;
+        vacancyCompany: string;
+        vacancyPosition: string;
+        status: string;
+        createdAt: Date | string;
+        updatedAt?: Date | string;
+    }
+    const collection: (clientId: string) => string;
+    const document: (clientId: string, suggestionId: string) => string;
+    const formatSummary: (suggestion: VacancySuggestion.Model) => string;
+    const createNew: (clientId: string, vacancyId: string, vacancyCompany: string, vacancyPosition: string, status?: string) => VacancySuggestion.Model;
+}

package/dist/models/VacancySuggestion.js

@@ -0,0 +1,18 @@
+export var VacancySuggestion;
+(function (VacancySuggestion) {
+    VacancySuggestion.collection = (clientId) => `clients/${clientId}/vacancySuggestions`;
+    VacancySuggestion.document = (clientId, suggestionId) => `clients/${clientId}/vacancySuggestions/${suggestionId}`;
+    VacancySuggestion.formatSummary = (suggestion) => {
+        return `${suggestion.vacancyPosition} at ${suggestion.vacancyCompany} (${suggestion.status})`;
+    };
+    VacancySuggestion.createNew = (clientId, vacancyId, vacancyCompany, vacancyPosition, status = "new") => {
+        return {
+            clientId,
+            vacancyId,
+            vacancyCompany,
+            vacancyPosition,
+            status,
+            createdAt: new Date().toISOString(),
+        };
+    };
+})(VacancySuggestion || (VacancySuggestion = {}));

package/dist/models/application.d.ts

@@ -0,0 +1,40 @@
+import { BaseModel } from "../BaseModel";
+export declare namespace Application {
+    /**
+     * Represents a job application
+     */
+    interface Model extends BaseModel {
+        vacancyId: string;
+        clientId: string;
+        status: "new" | "submitted" | "interviewing" | "accepted" | "rejected" | "withdrawn" | "applying" | "suggested" | "approved";
+        coverLetter?: string;
+        resume?: string;
+        company?: string;
+        position?: string;
+        location?: string;
+        jobId?: string;
+        advertisingUrl?: string;
+        applicationUrl?: string;
+        applicationDomain?: string;
+        advertisingDomain?: string;
+        description?: string;
+        fullPageText?: string;
+    }
+    const collection: (clientId: string) => string;
+    const document: (clientId: string, applicationId: string) => string;
+    const formatSummary: (application: Application.Model) => string;
+    const formatDate: (date: Date | string) => string;
+    const createNew: (clientId: string, vacancyId: string, vacancyData?: {
+        company?: string;
+        position?: string;
+        location?: string;
+        jobId?: string;
+        advertisingUrl?: string;
+        applicationUrl?: string;
+        applicationDomain?: string;
+        advertisingDomain?: string;
+        description?: string;
+        fullPageText?: string;
+    }) => Application.Model;
+    const updateStatus: (application: Application.Model, newStatus: Application.Model["status"]) => Application.Model;
+}

package/dist/models/application.js

@@ -0,0 +1,37 @@
+export var Application;
+(function (Application) {
+    Application.collection = (clientId) => `clients/${clientId}/applications`;
+    Application.document = (clientId, applicationId) => `clients/${clientId}/applications/${applicationId}`;
+    Application.formatSummary = (application) => {
+        return `${application.position} at ${application.company} (${application.status})`;
+    };
+    Application.formatDate = (date) => {
+        const dateObj = date instanceof Date ? date : new Date(date);
+        return dateObj.toLocaleDateString();
+    };
+    Application.createNew = (clientId, vacancyId, vacancyData = {}) => {
+        return {
+            clientId,
+            vacancyId,
+            status: "new",
+            company: vacancyData.company,
+            position: vacancyData.position,
+            location: vacancyData.location,
+            jobId: vacancyData.jobId,
+            advertisingUrl: vacancyData.advertisingUrl,
+            applicationUrl: vacancyData.applicationUrl,
+            applicationDomain: vacancyData.applicationDomain,
+            advertisingDomain: vacancyData.advertisingDomain,
+            description: vacancyData.description,
+            fullPageText: vacancyData.fullPageText,
+            createdAt: new Date().toISOString(),
+        };
+    };
+    Application.updateStatus = (application, newStatus) => {
+        return {
+            ...application,
+            status: newStatus,
+            updatedAt: new Date().toISOString(),
+        };
+    };
+})(Application || (Application = {}));

package/dist/models/authUser.d.ts

@@ -0,0 +1,31 @@
+import { BaseModel } from "../BaseModel";
+interface FirestoreTimestamp {
+    seconds: number;
+    nanoseconds: number;
+    _firestore_timestamp?: boolean;
+}
+/**
+ * AuthUser interface - replaces the old class-based model
+ */
+export interface AuthUser extends BaseModel {
+    email: string;
+    displayName?: string;
+    photoURL?: string;
+    lastSignIn?: Date | string;
+    emailVerified?: boolean;
+}
+export declare const AuthUserCollectionPath = "users";
+export declare const getAuthUserDocumentPath: (userId: string) => string;
+export declare const AuthUserUtils: {
+    getTimestampFields: () => string[];
+    isFirestoreTimestamp: (value: any) => value is FirestoreTimestamp;
+    fromFirebaseUser: (user: any) => AuthUser;
+    formatDates: (user: AuthUser) => {
+        lastSignIn: string;
+        createdAt: string;
+        updatedAt?: string;
+    };
+    toFirestore: (user: AuthUser) => Record<string, any>;
+    fromFirestore: (data: Record<string, any>) => AuthUser;
+};
+export {};

package/dist/models/authUser.js

@@ -0,0 +1,80 @@
+// Path constants
+export const AuthUserCollectionPath = "users";
+export const getAuthUserDocumentPath = (userId) => `users/${userId}`;
+// Helper utilities for working with AuthUser
+export const AuthUserUtils = {
+    // Get timestamp fields for AuthUser
+    getTimestampFields: () => [],
+    // Check if value is a Firestore timestamp
+    isFirestoreTimestamp: (value) => {
+        return (typeof value === "object" &&
+            value !== null &&
+            ("seconds" in value || "_firestore_timestamp" in value));
+    },
+    // Create from Firebase user object
+    fromFirebaseUser: (user) => {
+        return {
+            id: user.uid,
+            email: user.email,
+            displayName: user.displayName,
+            photoURL: user.photoURL,
+            emailVerified: user.emailVerified,
+            lastSignIn: new Date().toISOString(), // Current timestamp for new logins
+            createdAt: new Date().toISOString(),
+        };
+    },
+    // Convert dates to display format
+    formatDates: (user) => {
+        const formatDate = (dateValue) => {
+            if (!dateValue)
+                return "N/A";
+            const date = typeof dateValue === "string" ? new Date(dateValue) : dateValue;
+            return date.toLocaleString();
+        };
+        return {
+            lastSignIn: formatDate(user.lastSignIn),
+            createdAt: formatDate(user.createdAt),
+            updatedAt: user.updatedAt ? formatDate(user.updatedAt) : undefined,
+        };
+    },
+    // Convert AuthUser to format for storage
+    toFirestore: (user) => {
+        // Create a copy of the object without the id field
+        const { id, ...data } = user;
+        // Ensure dates are in ISO string format
+        if (data.lastSignIn && data.lastSignIn instanceof Date) {
+            data.lastSignIn = data.lastSignIn.toISOString();
+        }
+        if (data.createdAt && data.createdAt instanceof Date) {
+            data.createdAt = data.createdAt.toISOString();
+        }
+        if (data.updatedAt && data.updatedAt instanceof Date) {
+            data.updatedAt = data.updatedAt.toISOString();
+        }
+        else {
+            // Add standard updatedAt timestamp to all documents
+            data.updatedAt = new Date().toISOString();
+        }
+        return data;
+    },
+    // Convert from Firestore data to AuthUser
+    fromFirestore: (data) => {
+        // Convert any timestamp fields
+        const processedData = { ...data };
+        // Process each timestamp field
+        const timestampFields = [];
+        timestampFields.forEach((field) => {
+            if (data[field]) {
+                if (AuthUserUtils.isFirestoreTimestamp(data[field])) {
+                    // Convert Firestore timestamp to Date
+                    processedData[field] = new Date(data[field].seconds * 1000).toISOString();
+                }
+                else if (typeof data[field] === "string") {
+                    // Keep ISO string as is
+                    processedData[field] = data[field];
+                }
+            }
+        });
+        return processedData;
+    },
+};

package/dist/models/client.d.ts

@@ -0,0 +1,13 @@
+import { BaseModel } from "../BaseModel";
+export declare namespace Client {
+    interface Model extends BaseModel {
+        name: string;
+        email: string;
+        status: "active" | "inactive";
+        resume?: string;
+    }
+    const collection: () => string;
+    const document: (clientId: string) => string;
+    const formatClient: (client: Client.Model) => string;
+    const createNew: (name: string, email: string) => Client.Model;
+}

package/dist/models/client.js

@@ -0,0 +1,16 @@
+export var Client;
+(function (Client) {
+    Client.collection = () => "clients";
+    Client.document = (clientId) => `clients/${clientId}`;
+    Client.formatClient = (client) => {
+        return `${client.name} (${client.email}) - ${client.status}`;
+    };
+    Client.createNew = (name, email) => {
+        return {
+            name,
+            email,
+            status: "active",
+            createdAt: new Date().toISOString(),
+        };
+    };
+})(Client || (Client = {}));

package/dist/models/clientData.d.ts

@@ -0,0 +1,25 @@
+import { BaseModel } from "../BaseModel";
+export declare namespace ClientData {
+    /**
+     * Represents a user's personal data.
+     */
+    interface Model extends BaseModel {
+        firstName: string;
+        lastName: string;
+        middleName: string;
+        preferredName: string;
+        email: string;
+        phone: string;
+        address: string;
+        city: string;
+        state: string;
+        zip: string;
+        country: string;
+        linkedIn?: string;
+        countryPhoneCode?: string;
+    }
+    const collection: () => string;
+    const document: (clientDataId: string) => string;
+    const formatClientData: (clientData: ClientData.Model) => string;
+    const createNew: (firstName: string, lastName: string, email: string, phone: string, address: string, city: string, state: string, zip: string, country: string) => ClientData.Model;
+}

package/dist/models/clientData.js

@@ -0,0 +1,24 @@
+export var ClientData;
+(function (ClientData) {
+    ClientData.collection = () => "clientData";
+    ClientData.document = (clientDataId) => `clientData/${clientDataId}`;
+    ClientData.formatClientData = (clientData) => {
+        return `${clientData.firstName} ${clientData.lastName} (${clientData.email})`;
+    };
+    ClientData.createNew = (firstName, lastName, email, phone, address, city, state, zip, country) => {
+        return {
+            firstName,
+            lastName,
+            middleName: "",
+            preferredName: "",
+            email,
+            phone,
+            address,
+            city,
+            state,
+            zip,
+            country,
+            createdAt: new Date().toISOString(),
+        };
+    };
+})(ClientData || (ClientData = {}));

package/dist/models/clientLogin.d.ts

@@ -0,0 +1,18 @@
+import { BaseModel } from "../BaseModel";
+export declare namespace ClientLogin {
+    /**
+     * Represents login credentials for a client website
+     */
+    interface Model extends BaseModel {
+        userId: string;
+        url: string;
+        domain: string;
+        username?: string;
+        password: string;
+        email?: string;
+    }
+    const collection: (userId: string) => string;
+    const document: (userId: string, domain: string) => string;
+    const formatClientLogin: (clientLogin: ClientLogin.Model) => string;
+    const createNew: (userId: string, url: string, domain: string, password: string, username?: string, email?: string) => ClientLogin.Model;
+}

package/dist/models/clientLogin.js

@@ -0,0 +1,19 @@
+export var ClientLogin;
+(function (ClientLogin) {
+    ClientLogin.collection = (userId) => `clientLogins/${userId}`;
+    ClientLogin.document = (userId, domain) => `clientLogins/${userId}/logins/${domain}`;
+    ClientLogin.formatClientLogin = (clientLogin) => {
+        return `${clientLogin.domain} (${clientLogin.username || clientLogin.email || "no username"})`;
+    };
+    ClientLogin.createNew = (userId, url, domain, password, username, email) => {
+        return {
+            userId,
+            url,
+            domain,
+            password,
+            username,
+            email,
+            createdAt: new Date().toISOString(),
+        };
+    };
+})(ClientLogin || (ClientLogin = {}));

package/dist/models/question.d.ts

@@ -0,0 +1,34 @@
+import { BaseModel } from "../BaseModel";
+/**
+ * QuestionData interface defines the core data fields for a generic question.
+ */
+export interface QuestionData {
+    question: string;
+    options: string[];
+}
+/**
+ * Question interface - extends BaseModelInterface and includes QuestionData
+ */
+export interface Question extends BaseModel, QuestionData {
+}
+export interface ApplicationQuestion {
+    questionText: string;
+    type: "text";
+    answer?: string;
+}
+/**
+ * Represents ApplicationQuestion data including its Firestore document ID.
+ */
+export type ApplicationQuestionDocument = ApplicationQuestion & {
+    id: string;
+};
+/**
+ * Represents a question-answer pair stored centrally for a client.
+ * Assumes structure in clients/{clientId}/questions collection.
+ */
+export interface ClientQuestionAnswerPair {
+    id?: string;
+    questionText: string;
+    answer: string;
+    createdAt?: Date;
+}

package/dist/models/question.js

@@ -0,0 +1 @@
+export {};

package/dist/models/userLogin.js

@@ -0,0 +1,59 @@
+"use strict";
+// import { BaseModel } from "../BaseModel";
+// /**
+//  * ClientLogin interface - represents login credentials for a client website
+//  */
+// export interface ClientLogin extends BaseModel {
+//   userId: string;
+//   url: string;
+//   username?: string;
+//   password: string;
+//   email?: string;
+//   createdAt: Date | string;
+//   updatedAt?: Date | string;
+// }
+// // Helper functions for ClientLogin collections
+// export const getClientLoginCollectionPath = (userId: string) =>
+//   ClientLoginPaths.collection(userId);
+// export const getClientLoginDocumentPath = (userId: string, loginId: string) =>
+//   ClientLoginPaths.document(userId, loginId);
+// // Helper utilities for working with ClientLogins
+// export const ClientLoginUtils = {
+//   // Format dates for display
+//   formatDates: (
+//     login: ClientLogin
+//   ): { createdAt: string; updatedAt: string } => {
+//     const createdDate =
+//       login.createdAt instanceof Date
+//         ? login.createdAt
+//         : new Date(login.createdAt);
+//     const updatedDate = login.updatedAt
+//       ? login.updatedAt instanceof Date
+//         ? login.updatedAt
+//         : new Date(login.updatedAt)
+//       : createdDate;
+//     return {
+//       createdAt: createdDate.toLocaleDateString(),
+//       updatedAt: updatedDate.toLocaleDateString(),
+//     };
+//   },
+//   // Create a new login with defaults
+//   createNew: (
+//     userId: string,
+//     url: string,
+//     password: string,
+//     username?: string
+//   ): ClientLogin => {
+//     return {
+//       userId,
+//       url,
+//       username,
+//       password,
+//       createdAt: new Date().toISOString(),
+//     };
+//   },
+//   // Get display name for a login (e.g. for UI lists)
+//   getDisplayName: (login: ClientLogin): string => {
+//     return `${login.url} (${login.username || "no username"})`;
+//   },
+// };

package/dist/models/userQuestion.d.ts

@@ -0,0 +1,15 @@
+import { BaseModel } from "../BaseModel";
+/**
+ * UserQuestionData interface defines the core data fields for a user question.
+ */
+export interface UserQuestionData {
+    userId: string;
+    question: string;
+    answer: string;
+    options: string[];
+}
+/**
+ * UserQuestion interface - extends BaseModel and includes UserQuestionData
+ */
+export interface UserQuestion extends BaseModel, UserQuestionData {
+}

package/dist/models/userQuestion.js

@@ -0,0 +1,37 @@
+export {};
+// Remove the old class definition and path methods
+/*
+export class UserQuestion extends FirestoreModel {
+  userId!: string
+  question!: string
+  answer!: string
+  options!: string[]
+
+  constructor(data: { id?: string } & UserQuestionData) {
+    super(data)
+    if (!data.options) {
+      // Default options logic needs to move to creation site
+      // this.options = []
+    }
+  }
+
+  static buildPath(userId: string, id?: string): string {
+    let path = `users/${userId}/questions`
+    return id ? `${path}/${id}` : path
+  }
+
+  getDocPath(): string {
+    if (!this.id) throw new Error('Cannot get document path without an ID')
+    if (!this.userId) throw new Error('Missing userId for doc path')
+    return UserQuestion.buildPath(this.userId, this.id)
+  }
+
+  getColPath(): string {
+    if (!this.userId) throw new Error('Missing userId for col path')
+    return UserQuestion.buildPath(this.userId)
+  }
+}
+*/
+// Add helper path functions (assuming UserQuestionPaths exists)
+// export const getUserQuestionCollectionPath = (userId: string) => UserQuestionPaths.collection(userId);
+// export const getUserQuestionDocumentPath = (userId: string, questionId: string) => UserQuestionPaths.document(userId, questionId);

package/dist/models/vacancy.d.ts

@@ -0,0 +1,24 @@
+import { BaseModel } from "../BaseModel";
+export declare namespace Vacancy {
+    /**
+     * Represents a job vacancy
+     */
+    interface Model extends BaseModel {
+        company: string;
+        position: string;
+        location: string;
+        description: string;
+        advertisingUrl: string;
+        applicationUrl: string;
+        applicationDomain: string;
+        advertisingDomain: string;
+        fullPageText: string;
+        jobId: string;
+        suggestedTo?: string[];
+    }
+    const collection: () => string;
+    const document: (vacancyId: string) => string;
+    const formatSummary: (vacancy: Vacancy.Model) => string;
+    const formatDate: (date: Date | string) => string;
+    const createNew: (company: string, position: string, location: string, description: string, advertisingUrl: string, applicationUrl: string, applicationDomain: string, advertisingDomain: string, fullPageText: string, jobId: string) => Vacancy.Model;
+}

package/dist/models/vacancy.js

@@ -0,0 +1,27 @@
+export var Vacancy;
+(function (Vacancy) {
+    Vacancy.collection = () => "vacancies";
+    Vacancy.document = (vacancyId) => `vacancies/${vacancyId}`;
+    Vacancy.formatSummary = (vacancy) => {
+        return `${vacancy.position} at ${vacancy.company} (${vacancy.location})`;
+    };
+    Vacancy.formatDate = (date) => {
+        const dateObj = date instanceof Date ? date : new Date(date);
+        return dateObj.toLocaleDateString();
+    };
+    Vacancy.createNew = (company, position, location, description, advertisingUrl, applicationUrl, applicationDomain, advertisingDomain, fullPageText, jobId) => {
+        return {
+            company,
+            position,
+            location,
+            description,
+            advertisingUrl,
+            applicationUrl,
+            applicationDomain,
+            advertisingDomain,
+            fullPageText,
+            jobId,
+            createdAt: new Date().toISOString(),
+        };
+    };
+})(Vacancy || (Vacancy = {}));

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@jobsearch-works/firestore-models",
+  "version": "1.0.0",
+  "description": "A shared library for standardizing Firestore document schemas and paths across multiple projects",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "vitest",
+    "lint": "eslint ./src",
+    "clean": "rm -rf dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jobsearch-works/firestore-models"
+  },
+  "keywords": [
+    "firestore",
+    "typescript",
+    "schema",
+    "models",
+    "firebase",
+    "shared",
+    "types"
+  ],
+  "author": "JobSearch Works",
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.22.2"
+  },
+  "peerDependencies": {
+    "firebase": "^10.0.0"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.56.0",
+    "typescript": "^5.3.3",
+    "tsup": "^7.2.0",
+    "vitest": "^1.2.2",
+    "@vitest/coverage-v8": "^1.2.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}