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

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

@@ -1,40 +1,74 @@
 import { ContactDTO, ContactType } from "@/modules/contact/contact.dtos.js";
 import { ContactInfo } from "./contact-info.model.js";
 /**
- * Contact class that wraps the Zod schema and provides additional functionality
+ * 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 +76,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 +89,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 +105,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 +114,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 +122,105 @@ 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;
+    /**
+     * Creates a Contact instance from a JSON string.
+     *
+     * @static
+     * @param {string} jsonString - JSON string containing contact data
+     * @returns {Contact | undefined} Contact instance or undefined if parsing/validation fails
+     *
+     * @example
+     * ```typescript
+     * const jsonString = '{"id":"123","displayName":"John Doe",...}';
+     * const contact = Contact.fromJSON(jsonString);
+     * if (contact) {
+     *   console.log(contact.displayName);
+     * }
+     * ```
+     */
+    static fromJSON(jsonString: string): Contact | undefined;
     /**
      * 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 +229,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 +241,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 +249,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 +268,29 @@ export declare class Contact {
      */
     static is(obj: unknown): obj is Contact;
     /**
-     * Converts Payout instance to a plain object
+     * Converts the Contact instance to a plain object.
+     *
+     * @returns {ContactDTO} Plain object representation of the contact
+     *
+     * @example
+     * ```typescript
+     * const contact = Contact.from(contactData);
+     * const plainObject = contact?.toObject();
+     * // Use plainObject for API calls or storage
+     * ```
+     */
+    toObject(): ContactDTO;
+    /**
+     * Converts the Contact instance to a JSON string.
+     *
+     * @returns {string} JSON string representation of the contact
+     *
+     * @example
+     * ```typescript
+     * const contact = Contact.from(contactData);
+     * const jsonString = contact?.toJSON();
+     * localStorage.setItem('contact', jsonString);
+     * ```
      */
-    toJSON(): ContactDTO;
+    toJSON(): string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temboplus/afloat",
-  "version": "0.1.77-beta.7",
+  "version": "0.1.77-beta.8",
   "description": "A foundational library for Temboplus-Afloat projects.",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.esm.js",
@@ -58,6 +58,6 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
-    "@temboplus/frontend-core": "^0.2.19"
+    "@temboplus/frontend-core": "^0.2.20-beta.0"
   }
 }