@temboplus/afloat 0.1.77-beta.7 → 0.1.77-beta.9

package/dist/modules/contact/contact.model.d.ts

@@ -1,40 +1,144 @@
 import { ContactDTO, ContactType } from "@/modules/contact/contact.dtos.js";
 import { ContactInfo } from "./contact-info.model.js";
+import { z } from "zod";
 /**
- * Contact class that wraps the Zod schema and provides additional functionality
+ * Zod schema for Contact JSON serialization
+ * This schema validates the JSON representation of a Contact instance
+ *
+ * The Contact JSON format wraps the ContactDTO structure for consistency
+ * and future extensibility (e.g., adding metadata, version info)
+ */
+export declare const ContactJSONSchema: z.ZodObject<{
+    /** The complete contact data transfer object */
+    data: z.ZodObject<{
+        id: z.ZodString;
+        profileId: z.ZodString;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    } & {
+        displayName: z.ZodString;
+        accountNo: z.ZodString;
+        channel: z.ZodString;
+        type: z.ZodNativeEnum<typeof ContactType>;
+    }, "strip", z.ZodTypeAny, {
+        type: ContactType;
+        id: string;
+        displayName: string;
+        accountNo: string;
+        profileId: string;
+        createdAt: string;
+        updatedAt: string;
+        channel: string;
+    }, {
+        type: ContactType;
+        id: string;
+        displayName: string;
+        accountNo: string;
+        profileId: string;
+        createdAt: string;
+        updatedAt: string;
+        channel: string;
+    }>;
+    /** Version for future compatibility */
+    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    data: {
+        type: ContactType;
+        id: string;
+        displayName: string;
+        accountNo: string;
+        profileId: string;
+        createdAt: string;
+        updatedAt: string;
+        channel: string;
+    };
+}, {
+    data: {
+        type: ContactType;
+        id: string;
+        displayName: string;
+        accountNo: string;
+        profileId: string;
+        createdAt: string;
+        updatedAt: string;
+        channel: string;
+    };
+    version?: string | undefined;
+}>;
+/**
+ * Infer the ContactJSON type from the schema
+ */
+export type ContactJSON = z.infer<typeof ContactJSONSchema>;
+/**
+ * Contact class that wraps the Zod schema and provides additional functionality.
+ * Represents a contact entity with validation and type-safe access to contact information.
+ *
+ * @class Contact
+ *
+ * @example
+ * ```typescript
+ * // Preferred: Use static factory methods
+ * const contact = Contact.from(contactData);
+ *
+ * // From JSON
+ * const jsonContact = Contact.fromJSON(jsonString);
+ *
+ * // Type-safe access
+ * if (contact) {
+ *   console.log(contact.displayName);
+ *   console.log(contact.info?.channelName);
+ * }
+ * ```
  */
 export declare class Contact {
     private readonly data;
     /**
-     * Private constructor - use static methods to create instances
+     * Private constructor - use static factory methods to create instances.
+     *
+     * @deprecated Use {@link Contact.from} or other static factory methods instead
+     * @private
+     * @param {ContactDTO} data - Validated contact data
      */
     private constructor();
     /**
-     * Unique identifier for the contact
+     * Unique identifier for the contact.
+     *
+     * @returns {string} The contact's unique ID
      */
     get id(): string;
     /**
-     * Profile identifier associated with this contact
+     * Profile identifier associated with this contact.
+     *
+     * @returns {string} The profile ID
      */
     get profileId(): string;
     /**
-     * Display name of the contact
+     * Display name of the contact.
+     *
+     * @returns {string} The contact's display name
      */
     get displayName(): string;
     /**
-     * Type of contact (Bank or Mobile)
+     * Type of contact (Bank or Mobile).
+     *
+     * @returns {ContactType} The contact type
      */
     get type(): ContactType;
     /**
-     * Creation timestamp of the contact
+     * Creation timestamp of the contact.
+     *
+     * @returns {Date} The creation date
      */
     get createdAt(): Date;
     /**
-     * Update timestamp of the contact
+     * Update timestamp of the contact.
+     *
+     * @returns {Date} The last update date
      */
     get updatedAt(): Date;
     /**
-     * Detailed contact information based on contact type
+     * Detailed contact information based on contact type.
      *
      * @returns {ContactInfo | undefined} Contact information object:
      * - MobileContactInfo for mobile money contacts
@@ -42,12 +146,12 @@ export declare class Contact {
      * - undefined if contact information cannot be constructed
      *
      * @remarks
-     * For mobile contacts, constructs from phone number
-     * For bank contacts, constructs from SWIFT code and account number
+     * For mobile contacts, constructs from phone number.
+     * For bank contacts, constructs from SWIFT code and account number.
      */
     get info(): ContactInfo | undefined;
     /**
-     * Account number for the contact
+     * Account number for the contact.
      *
      * @returns {string} Account number:
      * - For valid contacts, returns formatted account number from ContactInfo
@@ -55,12 +159,14 @@ export declare class Contact {
      */
     get accNo(): string;
     /**
-     * Account name for the contact
-     * Always returns the display name
+     * Account name for the contact.
+     * Always returns the display name.
+     *
+     * @returns {string} The account name
      */
     get accName(): string;
     /**
-     * Label for the account number field based on contact type
+     * Label for the account number field based on contact type.
      *
      * @returns {string} Appropriate label:
      * - "Phone Number" for mobile contacts
@@ -69,7 +175,7 @@ export declare class Contact {
      */
     get accNoLabel(): string;
     /**
-     * Label for the channel field based on contact type
+     * Label for the channel field based on contact type.
      *
      * @returns {string} Appropriate label:
      * - "Channel" for mobile contacts
@@ -78,7 +184,7 @@ export declare class Contact {
      */
     get channelLabel(): string;
     /**
-     * Label for the account name field based on contact type
+     * Label for the account name field based on contact type.
      *
      * @returns {string} Appropriate label:
      * - "Full Name" for mobile contacts
@@ -86,26 +192,88 @@ export declare class Contact {
      * - "Display Name" as fallback
      */
     get accNameLabel(): string;
+    /**
+     * Human-readable channel name for the contact.
+     *
+     * @returns {string} The channel name (e.g., "M-Pesa", "CRDB") or empty string
+     */
     get channelName(): string;
     /**
-     * Creates a Contact instance from raw data
-     * @throws {ZodError} if validation fails
+     * Creates a Contact instance from raw data.
+     * This is the preferred method for creating Contact instances.
+     *
+     * @static
+     * @param {ContactDTO} data - Raw contact data to validate and wrap
+     * @returns {Contact | undefined} Contact instance or undefined if validation fails
+     *
+     * @example
+     * ```typescript
+     * const contact = Contact.from({
+     *   id: "123",
+     *   profileId: "profile-456",
+     *   displayName: "John Doe",
+     *   type: "Mobile",
+     *   accountNo: "+255712345678",
+     *   channel: "VODACOM",
+     *   createdAt: "2024-01-01T00:00:00Z",
+     *   updatedAt: "2024-01-01T00:00:00Z"
+     * });
+     * ```
+     */
+    static from(data: ContactDTO): Contact | undefined;
+    /**
+     * Creates a Contact instance from raw data, throwing on validation failure.
+     *
+     * @static
+     * @param {ContactDTO} data - Raw contact data to validate and wrap
+     * @returns {Contact} Contact instance
+     * @throws {ZodError} If validation fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const contact = Contact.create(contactData);
+     * } catch (error) {
+     *   console.error("Validation failed:", error);
+     * }
+     * ```
      */
     static create(data: ContactDTO): Contact;
     /**
-     * Creates multiple Contact instances from an array of raw data
-     * @throws {ZodError} if validation fails for any item
+     * Creates multiple Contact instances from an array of raw data.
+     *
+     * @static
+     * @param {ContactDTO[]} dataArray - Array of contact data
+     * @returns {Contact[]} Array of Contact instances
+     * @throws {ZodError} If validation fails for any item
+     *
+     * @example
+     * ```typescript
+     * const contacts = Contact.createMany([contactData1, contactData2]);
+     * ```
      */
     static createMany(dataArray: ContactDTO[]): Contact[];
     /**
-     * Creates a Contact instance from raw data without throwing
+     * Creates a Contact instance from raw data without throwing.
+     *
+     * @static
+     * @param {ContactDTO} data - Raw contact data
      * @returns {Contact | null} Contact instance or null if validation fails
+     *
+     * @example
+     * ```typescript
+     * const contact = Contact.createSafe(contactData);
+     * if (contact) {
+     *   console.log("Contact created successfully");
+     * }
+     * ```
      */
     static createSafe(data: ContactDTO): Contact | null;
     /**
      * Checks if an unknown value contains valid data to construct a Contact instance.
      * This is useful when validating raw data structures before instantiation.
      *
+     * @static
      * @param {unknown} obj - The value containing potential contact data
      * @returns {obj is Contact} Type predicate indicating if a Contact can be constructed
      *
@@ -114,13 +282,10 @@ export declare class Contact {
      * const rawData = await fetchFromAPI();
      * if (Contact.canConstruct(rawData)) {
      *   const contact = Contact.create(rawData);
-     *   // TypeScript knows contact is valid here
      *   console.log(contact.displayName);
      * }
      * ```
      *
-     * @throws {never} This method never throws errors
-     *
      * @remarks
      * This method performs strict validation against the {@link ContactDTO} schema.
      */
@@ -129,6 +294,7 @@ export declare class Contact {
      * Validates if an unknown value is a Contact instance.
      * This is a runtime type guard that ensures proper object structure and data validity.
      *
+     * @static
      * @param {unknown} obj - The value to validate
      * @returns {obj is Contact} Type predicate indicating if the value is a valid Contact
      *
@@ -136,18 +302,15 @@ export declare class Contact {
      * ```typescript
      * const maybeContact = getContactFromCache();
      * if (Contact.is(maybeContact)) {
-     *   // TypeScript knows maybeContact is a Contact here
-     *   console.log(maybeContact.displayName);
+     *   console.log(maybeContact.displayName); // Type-safe
      * }
      * ```
      *
-     * @throws {never} This method never throws errors
-     *
      * @remarks
      * This method performs a complete structural validation:
      * 1. Checks if the value is an object
      * 2. Verifies presence of internal data property
-     * 3. Validates the data against ContactData schema
+     * 3. Validates the data against ContactDTO schema
      * 4. Ensures the object is a proper Contact instance
      *
      * Use this method when:
@@ -158,7 +321,121 @@ export declare class Contact {
      */
     static is(obj: unknown): obj is Contact;
     /**
-     * Converts Payout instance to a plain object
+     * Serializes the Contact instance to a JSON-compatible object
+     *
+     * This method creates a structured representation suitable for storage or transmission.
+     * The serialized format includes all contact data and a version identifier for
+     * future compatibility.
+     *
+     * @returns {ContactJSON} JSON-compatible object representation
+     *
+     * @example
+     * ```typescript
+     * const contact = Contact.from(contactData);
+     * const json = contact.toJSON();
+     * // { data: { id: "123", displayName: "John", ... }, version: "1.0" }
+     *
+     * // Store in localStorage
+     * localStorage.setItem('contact', JSON.stringify(json));
+     * ```
+     */
+    toJSON(): ContactJSON;
+    /**
+     * Serializes the Contact instance to a JSON string
+     *
+     * Convenience method that combines toJSON() with JSON.stringify()
+     *
+     * @returns {string} JSON string representation
+     *
+     * @example
+     * ```typescript
+     * const contact = Contact.from(contactData);
+     * const jsonString = contact.toJSONString();
+     * localStorage.setItem('contact', jsonString);
+     * ```
+     */
+    toJSONString(): string;
+    /**
+     * Creates a Contact instance from a JSON-compatible object or string
+     *
+     * This static method reconstructs a Contact instance from data that was
+     * previously serialized using toJSON(). It performs comprehensive validation
+     * to ensure data integrity.
+     *
+     * **Validation Process:**
+     * 1. Parses JSON string if provided
+     * 2. Validates structure using Zod schema
+     * 3. Extracts and validates ContactDTO data
+     * 4. Constructs Contact instance with validated data
+     *
+     * @static
+     * @param {ContactJSON | string} json - JSON object or string containing contact data
+     * @returns {Contact | undefined} New Contact instance if successful, undefined if parsing/validation fails
+     *
+     * @example
+     * ```typescript
+     * // From JSON object
+     * const json = { data: { id: "123", displayName: "John", ... }, version: "1.0" };
+     * const contact = Contact.fromJSON(json);
+     *
+     * // From JSON string
+     * const jsonString = localStorage.getItem('contact');
+     * const contact = Contact.fromJSON(jsonString);
+     *
+     * // With error handling
+     * const contact = Contact.fromJSON(jsonString);
+     * if (contact) {
+     *   console.log("Contact restored:", contact.displayName);
+     * } else {
+     *   console.error("Failed to restore contact from JSON");
+     * }
+     * ```
+     */
+    static fromJSON(json: ContactJSON | string): Contact | undefined;
+    /**
+     * Creates a Contact instance from a JSON string
+     *
+     * Convenience method that delegates to fromJSON()
+     *
+     * @static
+     * @param {string} jsonString - JSON string containing contact data
+     * @returns {Contact | undefined} New Contact instance if successful, undefined if parsing fails
+     *
+     * @example
+     * ```typescript
+     * const jsonString = '{"data":{"id":"123","displayName":"John",...},"version":"1.0"}';
+     * const contact = Contact.fromJSONString(jsonString);
+     * ```
+     */
+    static fromJSONString(jsonString: string): Contact | undefined;
+    /**
+     * Type guard to check if an object is a valid ContactJSON using Zod validation
+     *
+     * This method validates the structure of a JSON object to ensure it contains
+     * all required fields and meets the ContactJSON schema requirements.
+     *
+     * @static
+     * @param {unknown} obj - The object to validate
+     * @returns {obj is ContactJSON} Type predicate indicating if the object is valid ContactJSON
+     *
+     * @example
+     * ```typescript
+     * const data = JSON.parse(jsonString);
+     *
+     * if (Contact.isContactJSON(data)) {
+     *   // TypeScript now knows data is ContactJSON
+     *   const contact = Contact.fromJSON(data);
+     * } else {
+     *   console.error("Invalid ContactJSON structure");
+     * }
+     * ```
+     *
+     * @remarks
+     * Use this method when:
+     * - Validating JSON data before deserialization
+     * - Implementing type guards in conditional logic
+     * - Checking API responses before processing
+     * - Validating cached data integrity
      */
-    toJSON(): ContactDTO;
+    static isContactJSON(obj: unknown): obj is ContactJSON;
 }

package/dist/modules/login/login.model.d.ts

@@ -1,10 +1,43 @@
 import { LogInDTO } from "./login.dtos.js";
-export type LogInJson = {
+import { z } from "zod";
+/**
+ * Zod schema for LogIn JSON serialization
+ * This schema validates the JSON representation of a LogIn instance
+ */
+export declare const LogInJSONSchema: z.ZodObject<{
+    id: z.ZodString;
+    profileId: z.ZodString;
+    name: z.ZodString;
+    identity: z.ZodString;
+    type: z.ZodString;
+    roleId: z.ZodString;
+    isActive: z.ZodBoolean;
+    isArchived: z.ZodBoolean;
+    resetPassword: z.ZodBoolean;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    access: z.ZodArray<z.ZodString, "many">;
+    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    name: string;
     id: string;
+    version: string;
     profileId: string;
-    name: string;
     identity: string;
+    roleId: string;
+    isActive: boolean;
+    isArchived: boolean;
+    resetPassword: boolean;
+    createdAt: string;
+    updatedAt: string;
+    access: string[];
+}, {
     type: string;
+    name: string;
+    id: string;
+    profileId: string;
+    identity: string;
     roleId: string;
     isActive: boolean;
     isArchived: boolean;
@@ -12,7 +45,12 @@ export type LogInJson = {
     createdAt: string;
     updatedAt: string;
     access: string[];
-};
+    version?: string | undefined;
+}>;
+/**
+ * Infer the LogInJSON type from the schema
+ */
+export type LogInJSON = z.infer<typeof LogInJSONSchema>;
 /**
  * Represents the authenticated user's identity and account information.
  *
@@ -63,18 +101,6 @@ export declare class LogIn {
      * ```
      */
     static from(dto: LogInDTO): LogIn;
-    /**
-     * Creates a LogIn instance from a JSON string.
-     *
-     * @param json - JSON string containing login data
-     * @returns A new LogIn instance, or undefined if parsing failed
-     *
-     * @example
-     * ```typescript
-     * const logIn = LogIn.fromJson('{"id":"abc","name":"John",...}');
-     * ```
-     */
-    static fromJson(json: string): LogIn | undefined;
     /**
      * Gets the user's unique identifier.
      */
@@ -124,15 +150,19 @@ export declare class LogIn {
      */
     get access(): ReadonlyArray<string>;
     /**
-     * Converts the LogIn instance to a plain object.
-     *
-     * @returns A plain object representation
+    * Serializes the LogIn instance to a JSON-compatible object
+    */
+    toJSON(): LogInJSON;
+    /**
+     * Serializes the LogIn instance to a JSON string
      */
-    toObject(): LogInJson;
+    toJSONString(): string;
     /**
-     * Converts the LogIn instance to a JSON string.
-     *
-     * @returns A JSON string representation
+     * Creates a LogIn instance from a JSON-compatible object or string
+     */
+    static fromJSON(json: LogInJSON | string): LogIn | undefined;
+    /**
+     * Type guard using Zod schema validation
      */
-    toJson(): string;
+    static isLogInJSON(obj: unknown): obj is LogInJSON;
 }