@temboplus/afloat 0.1.81 → 0.2.0-beta.10

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

@@ -0,0 +1,450 @@
+import { BeneficiaryDTO, BeneficiaryType } from "@/modules/beneficiary/beneficiary.dtos.js";
+import { BeneficiaryInfo } from "./beneficiary-info.model.js";
+import { z } from "zod";
+/**
+ * Zod schema for Beneficiary JSON serialization
+ * This schema validates the JSON representation of a Beneficiary instance
+ *
+ * The Beneficiary JSON format wraps the BeneficiaryDTO structure for consistency
+ * and future extensibility (e.g., adding metadata, version info)
+ */
+export declare const BeneficiaryJSONSchema: z.ZodObject<{
+    /** The complete beneficiary 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 BeneficiaryType>;
+    }, "strip", z.ZodTypeAny, {
+        type: BeneficiaryType;
+        createdAt: string;
+        id: string;
+        displayName: string;
+        accountNo: string;
+        profileId: string;
+        updatedAt: string;
+        channel: string;
+    }, {
+        type: BeneficiaryType;
+        createdAt: string;
+        id: string;
+        displayName: string;
+        accountNo: string;
+        profileId: string;
+        updatedAt: string;
+        channel: string;
+    }>;
+    /** Version for future compatibility */
+    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    data: {
+        type: BeneficiaryType;
+        createdAt: string;
+        id: string;
+        displayName: string;
+        accountNo: string;
+        profileId: string;
+        updatedAt: string;
+        channel: string;
+    };
+}, {
+    data: {
+        type: BeneficiaryType;
+        createdAt: string;
+        id: string;
+        displayName: string;
+        accountNo: string;
+        profileId: string;
+        updatedAt: string;
+        channel: string;
+    };
+    version?: string | undefined;
+}>;
+/**
+ * Infer the BeneficiaryJSON type from the schema
+ */
+export type BeneficiaryJSON = z.infer<typeof BeneficiaryJSONSchema>;
+/**
+ * Beneficiary class that wraps the Zod schema and provides additional functionality.
+ * Represents a beneficiary entity with validation and type-safe access to beneficiary information.
+ *
+ * @class Beneficiary
+ *
+ * @example
+ * ```typescript
+ * // Preferred: Use static factory methods
+ * const beneficiary = Beneficiary.from(beneficiaryData);
+ *
+ * // From JSON
+ * const jsonBeneficiary = Beneficiary.fromJSON(jsonString);
+ *
+ * // Type-safe access
+ * if (beneficiary) {
+ *   console.log(beneficiary.displayName);
+ *   console.log(beneficiary.info?.channelName);
+ * }
+ * ```
+ */
+export declare class Beneficiary {
+    private readonly data;
+    private _info;
+    private _infoComputed;
+    /**
+     * Private constructor - use static factory methods to create instances.
+     *
+     * @deprecated Use {@link Beneficiary.from} or other static factory methods instead
+     * @private
+     * @param {BeneficiaryDTO} data - Validated beneficiary data
+     */
+    private constructor();
+    /**
+     * Unique identifier for the beneficiary.
+     *
+     * @returns {string} The beneficiary's unique ID
+     */
+    get id(): string;
+    /**
+     * Profile identifier associated with this beneficiary.
+     *
+     * @returns {string} The profile ID
+     */
+    get profileId(): string;
+    /**
+     * Display name of the beneficiary.
+     *
+     * @returns {string} The beneficiary's display name
+     */
+    get displayName(): string;
+    /**
+     * Type of beneficiary (Bank or Mobile).
+     *
+     * @returns {BeneficiaryType} The beneficiary type
+     */
+    get type(): BeneficiaryType;
+    /**
+     * Creation timestamp of the beneficiary.
+     *
+     * @returns {Date} The creation date
+     */
+    get createdAt(): Date;
+    /**
+     * Update timestamp of the beneficiary.
+     *
+     * @returns {Date} The last update date
+     */
+    get updatedAt(): Date;
+    /**
+     * Detailed beneficiary information based on beneficiary type.
+     *
+     * @returns {BeneficiaryInfo | undefined} Beneficiary information object:
+     * - MobileBeneficiaryInfo for mobile money beneficiaries
+     * - BankBeneficiaryInfo for bank beneficiaries
+     * - undefined if beneficiary information cannot be constructed
+     *
+     * @remarks
+     * For mobile beneficiaries, constructs from phone number.
+     * For bank beneficiaries, constructs from SWIFT code and account number.
+     *
+     * Result is memoised — repeated accesses don't re-parse the phone number or
+     * re-resolve the bank.
+     */
+    get info(): BeneficiaryInfo | undefined;
+    /**
+     * Account number for the beneficiary.
+     *
+     * @returns {string} Account number:
+     * - For valid beneficiaries, returns formatted account number from BeneficiaryInfo
+     * - For invalid beneficiaries, falls back to raw account number
+     */
+    get accNo(): string;
+    /**
+     * Account name for the beneficiary.
+     * Always returns the display name.
+     *
+     * @returns {string} The account name
+     */
+    get accName(): string;
+    /**
+     * Label for the account number field based on beneficiary type.
+     *
+     * @returns {string} Appropriate label:
+     * - "Phone Number" for mobile beneficiaries
+     * - "Bank Account Number" for bank beneficiaries
+     * - "Account Number" as fallback
+     */
+    get accNoLabel(): string;
+    /**
+     * Label for the channel field based on beneficiary type.
+     *
+     * @returns {string} Appropriate label:
+     * - "Channel" for mobile beneficiaries
+     * - "Bank" for bank beneficiaries
+     * - "Channel" as fallback
+     */
+    get channelLabel(): string;
+    /**
+     * Label for the account name field based on beneficiary type.
+     *
+     * @returns {string} Appropriate label:
+     * - "Full Name" for mobile beneficiaries
+     * - "Bank Account Name" for bank beneficiaries
+     * - "Display Name" as fallback
+     */
+    get accNameLabel(): string;
+    /**
+     * Human-readable channel name for the beneficiary.
+     *
+     * @returns {string} The channel name (e.g., "M-Pesa", "CRDB") or empty string
+     */
+    get channelName(): string;
+    /**
+     * Creates a Beneficiary instance from raw data.
+     * This is the preferred method for creating Beneficiary instances.
+     *
+     * @static
+     * @param {BeneficiaryDTO} data - Raw beneficiary data to validate and wrap
+     * @returns {Beneficiary | undefined} Beneficiary instance or undefined if validation fails
+     *
+     * @example
+     * ```typescript
+     * const beneficiary = Beneficiary.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: BeneficiaryDTO): Beneficiary | undefined;
+    /**
+     * Creates a Beneficiary instance from raw data, throwing on validation failure.
+     *
+     * @static
+     * @param {BeneficiaryDTO} data - Raw beneficiary data to validate and wrap
+     * @returns {Beneficiary} Beneficiary instance
+     * @throws {ZodError} If validation fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const beneficiary = Beneficiary.create(beneficiaryData);
+     * } catch (error) {
+     *   console.error("Validation failed:", error);
+     * }
+     * ```
+     */
+    static create(data: BeneficiaryDTO): Beneficiary;
+    /**
+     * Creates multiple Beneficiary instances from an array of raw data.
+     *
+     * @static
+     * @param {BeneficiaryDTO[]} dataArray - Array of beneficiary data
+     * @returns {Beneficiary[]} Array of Beneficiary instances
+     * @throws {ZodError} If validation fails for any item
+     *
+     * @example
+     * ```typescript
+     * const beneficiaries = Beneficiary.createMany([beneficiaryData1, beneficiaryData2]);
+     * ```
+     */
+    static createMany(dataArray: BeneficiaryDTO[]): Beneficiary[];
+    /**
+     * Creates a Beneficiary instance from raw data without throwing.
+     *
+     * @static
+     * @param {BeneficiaryDTO} data - Raw beneficiary data
+     * @returns {Beneficiary | null} Beneficiary instance or null if validation fails
+     *
+     * @example
+     * ```typescript
+     * const beneficiary = Beneficiary.createSafe(beneficiaryData);
+     * if (beneficiary) {
+     *   console.log("Beneficiary created successfully");
+     * }
+     * ```
+     */
+    static createSafe(data: BeneficiaryDTO): Beneficiary | null;
+    /**
+     * Checks if an unknown value contains valid data to construct a Beneficiary instance.
+     * This is useful when validating raw data structures before instantiation.
+     *
+     * @static
+     * @param {unknown} obj - The value containing potential beneficiary data
+     * @returns {obj is BeneficiaryDTO} Type predicate indicating the value is a valid BeneficiaryDTO
+     *
+     * @example
+     * ```typescript
+     * const rawData = await fetchFromAPI();
+     * if (Beneficiary.canConstruct(rawData)) {
+     *   const beneficiary = Beneficiary.create(rawData);
+     *   console.log(beneficiary.displayName);
+     * }
+     * ```
+     *
+     * @remarks
+     * This method performs strict validation against the {@link BeneficiaryDTO} schema.
+     *
+     * The predicate narrows to {@link BeneficiaryDTO} (not `Beneficiary`) — what
+     * `obj` actually is on success — so callers don't accidentally try to use
+     * instance methods like `toJSON()` on a raw DTO.
+     */
+    static canConstruct(obj: unknown): obj is BeneficiaryDTO;
+    /**
+     * Validates if an unknown value is a Beneficiary 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 Beneficiary} Type predicate indicating if the value is a valid Beneficiary
+     *
+     * @example
+     * ```typescript
+     * const maybeBeneficiary = getBeneficiaryFromCache();
+     * if (Beneficiary.is(maybeBeneficiary)) {
+     *   console.log(maybeBeneficiary.displayName); // Type-safe
+     * }
+     * ```
+     *
+     * @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 BeneficiaryDTO schema
+     * 4. Ensures the object is a proper Beneficiary instance
+     *
+     * Use this method when:
+     * - Validating cached Beneficiary instances
+     * - Checking serialized Beneficiary objects
+     * - Verifying API responses
+     * - Type narrowing in conditional blocks
+     */
+    static is(obj: unknown): obj is Beneficiary;
+    /**
+     * Serializes the Beneficiary instance to a JSON-compatible object
+     *
+     * This method creates a structured representation suitable for storage or transmission.
+     * The serialized format includes all beneficiary data and a version identifier for
+     * future compatibility.
+     *
+     * @returns {BeneficiaryJSON} JSON-compatible object representation
+     *
+     * @example
+     * ```typescript
+     * const beneficiary = Beneficiary.from(beneficiaryData);
+     * const json = beneficiary.toJSON();
+     * // { data: { id: "123", displayName: "John", ... }, version: "1.0" }
+     *
+     * // Store in localStorage
+     * localStorage.setItem('beneficiary', JSON.stringify(json));
+     * ```
+     */
+    toJSON(): BeneficiaryJSON;
+    /**
+     * Serializes the Beneficiary instance to a JSON string
+     *
+     * Convenience method that combines toJSON() with JSON.stringify()
+     *
+     * @returns {string} JSON string representation
+     *
+     * @example
+     * ```typescript
+     * const beneficiary = Beneficiary.from(beneficiaryData);
+     * const jsonString = beneficiary.toJSONString();
+     * localStorage.setItem('beneficiary', jsonString);
+     * ```
+     */
+    toJSONString(): string;
+    /**
+     * Creates a Beneficiary instance from a JSON-compatible object or string
+     *
+     * This static method reconstructs a Beneficiary 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 BeneficiaryDTO data
+     * 4. Constructs Beneficiary instance with validated data
+     *
+     * @static
+     * @param {BeneficiaryJSON | string} json - JSON object or string containing beneficiary data
+     * @returns {Beneficiary | undefined} New Beneficiary instance if successful, undefined if parsing/validation fails
+     *
+     * @example
+     * ```typescript
+     * // From JSON object
+     * const json = { data: { id: "123", displayName: "John", ... }, version: "1.0" };
+     * const beneficiary = Beneficiary.fromJSON(json);
+     *
+     * // From JSON string
+     * const jsonString = localStorage.getItem('beneficiary');
+     * const beneficiary = Beneficiary.fromJSON(jsonString);
+     *
+     * // With error handling
+     * const beneficiary = Beneficiary.fromJSON(jsonString);
+     * if (beneficiary) {
+     *   console.log("Beneficiary restored:", beneficiary.displayName);
+     * } else {
+     *   console.error("Failed to restore beneficiary from JSON");
+     * }
+     * ```
+     */
+    static fromJSON(json: BeneficiaryJSON | string): Beneficiary | undefined;
+    /**
+     * Creates a Beneficiary instance from a JSON string
+     *
+     * Convenience method that delegates to fromJSON()
+     *
+     * @static
+     * @param {string} jsonString - JSON string containing beneficiary data
+     * @returns {Beneficiary | undefined} New Beneficiary instance if successful, undefined if parsing fails
+     *
+     * @example
+     * ```typescript
+     * const jsonString = '{"data":{"id":"123","displayName":"John",...},"version":"1.0"}';
+     * const beneficiary = Beneficiary.fromJSONString(jsonString);
+     * ```
+     */
+    static fromJSONString(jsonString: string): Beneficiary | undefined;
+    /**
+     * Type guard to check if an object is a valid BeneficiaryJSON using Zod validation
+     *
+     * This method validates the structure of a JSON object to ensure it contains
+     * all required fields and meets the BeneficiaryJSON schema requirements.
+     *
+     * @static
+     * @param {unknown} obj - The object to validate
+     * @returns {obj is BeneficiaryJSON} Type predicate indicating if the object is valid BeneficiaryJSON
+     *
+     * @example
+     * ```typescript
+     * const data = JSON.parse(jsonString);
+     *
+     * if (Beneficiary.isBeneficiaryJSON(data)) {
+     *   // TypeScript now knows data is BeneficiaryJSON
+     *   const beneficiary = Beneficiary.fromJSON(data);
+     * } else {
+     *   console.error("Invalid BeneficiaryJSON 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
+     */
+    static isBeneficiaryJSON(obj: unknown): obj is BeneficiaryJSON;
+}

package/dist/modules/beneficiary/beneficiary.repository.d.ts

@@ -0,0 +1,116 @@
+import { BaseRepository } from "@/lib/api/base-repository.js";
+import { BeneficiaryInfo } from "@/modules/beneficiary/beneficiary-info.model.js";
+import { Beneficiary } from "@/modules/beneficiary/beneficiary.model.js";
+import { contract } from "./beneficiary.api-contract.js";
+/**
+ * Repository class for managing Beneficiary data through API interactions.
+ * Handles beneficiary creation, updates, deletion, and retrieval operations.
+ *
+ * This repository handles pure API communication without permission checking.
+ * Permission validation should be handled at the service layer or route handlers.
+ *
+ * @extends {BaseRepository<typeof contract>}
+ *
+ * @example
+ * ```typescript
+ * const repo = new BeneficiaryRepository({ token: userToken });
+ * const beneficiaries = await repo.getAll();
+ * ```
+ */
+export declare class BeneficiaryRepository extends BaseRepository<typeof contract> {
+    /**
+     * Creates an instance of BeneficiaryRepository using the beneficiary contract.
+     *
+     * @param options - Optional configuration
+     * @param options.token - Authentication token for API calls
+     * @param options.root - Custom API root URL
+     *
+     * @example
+     * ```typescript
+     * const repo = new BeneficiaryRepository({
+     *   token: "user-auth-token",
+     *   root: "https://api-staging.afloat.money/v1"
+     * });
+     * ```
+     */
+    constructor(options?: {
+        token?: string;
+        root?: string;
+    });
+    /**
+     * Creates a new beneficiary record.
+     *
+     * @param info - The data required to create a new beneficiary
+     * @returns Promise that resolves to the newly created beneficiary
+     * @throws {APIError} If the creation operation fails
+     *
+     * @example
+     * ```typescript
+     * const newBeneficiary = await repo.create({
+     *   name: "John Doe",
+     *   email: "john@example.com",
+     *   phone: "+1234567890"
+     * });
+     * ```
+     */
+    create(info: BeneficiaryInfo): Promise<Beneficiary>;
+    /**
+     * Updates an existing beneficiary record by ID.
+     *
+     * @param id - The unique identifier of the beneficiary to edit
+     * @param info - The data to update the beneficiary with
+     * @returns Promise that resolves to the updated beneficiary
+     * @throws {APIError} If the update operation fails
+     *
+     * @example
+     * ```typescript
+     * const updatedBeneficiary = await repo.edit("beneficiary-id", {
+     *   name: "Jane Doe",
+     *   email: "jane@example.com"
+     * });
+     * ```
+     */
+    edit(id: string, info: BeneficiaryInfo): Promise<Beneficiary>;
+    /**
+     * Deletes a beneficiary record by ID.
+     *
+     * @param id - The unique identifier of the beneficiary to remove
+     * @returns Promise that resolves when the deletion is complete
+     * @throws {APIError} If the deletion operation fails
+     *
+     * @example
+     * ```typescript
+     * await repo.remove("beneficiary-id");
+     * console.log("Beneficiary deleted successfully");
+     * ```
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Retrieves all beneficiaries.
+     * Results are ordered in descending order by creation date by default.
+     *
+     * @returns Promise that resolves to an array of beneficiaries
+     * @throws {APIError} If the fetch operation fails
+     *
+     * @example
+     * ```typescript
+     * const beneficiaries = await repo.getAll();
+     * beneficiaries.forEach(beneficiary => console.log(`Beneficiary: ${beneficiary.name}`));
+     * ```
+     */
+    getAll(): Promise<Beneficiary[]>;
+    /**
+     * Retrieves a beneficiary by its unique identifier.
+     *
+     * @param id - The unique identifier of the beneficiary to retrieve
+     * @returns Promise that resolves to the requested beneficiary
+     * @throws {APIError} If the beneficiary is not found or fetch operation fails
+     *
+     * @example
+     * ```typescript
+     * const beneficiary = await repo.getByID("beneficiary-id");
+     * console.log(`Beneficiary: ${beneficiary.name}, Email: ${beneficiary.email}`);
+     * ```
+     */
+    getByID(id: string): Promise<Beneficiary>;
+}

package/dist/modules/beneficiary/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./beneficiary.repository.js";
+export * from "./beneficiary.dtos.js";
+export { BankBeneficiaryInfo, BankBeneficiaryJSONSchema, BeneficiaryError, BeneficiaryInfo, BeneficiaryJSONSchema as BeneficiaryInfoJSONSchema, MobileBeneficiaryInfo, MobileBeneficiaryJSONSchema, type BankBeneficiaryJSON, type BeneficiaryJSON as BeneficiaryInfoJSON, type MobileBeneficiaryJSON, } from "./beneficiary-info.model.js";
+export { Beneficiary, BeneficiaryJSONSchema, type BeneficiaryJSON, } from "./beneficiary.model.js";
+export * from "./beneficiary-input-handler.js";
+export * from "./beneficiary.api-contract.js";

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

@@ -0,0 +1,4 @@
+export * from "./login.dtos.js";
+export * from "./login.model.js";
+export * from "./login.repository.js";
+export * from "./permission.type.js";

package/dist/modules/login/login.api-contract.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Identity API contract
+ */
+export declare const identityContract: {
+    getUserCredentials: {
+        method: "GET";
+        path: "/me";
+        responses: {
+            200: import("zod").ZodObject<{
+                id: import("zod").ZodString;
+                profileId: import("zod").ZodString;
+                name: import("zod").ZodString;
+                identity: import("zod").ZodString;
+                type: import("zod").ZodString;
+                roleId: import("zod").ZodString;
+                isActive: import("zod").ZodBoolean;
+                isArchived: import("zod").ZodBoolean;
+                resetPassword: import("zod").ZodBoolean;
+                createdAt: import("zod").ZodString;
+                updatedAt: import("zod").ZodString;
+                access: import("zod").ZodArray<import("zod").ZodString, "many">;
+            }, "strip", import("zod").ZodTypeAny, {
+                type: string;
+                name: string;
+                createdAt: string;
+                id: string;
+                profileId: string;
+                identity: string;
+                roleId: string;
+                isActive: boolean;
+                isArchived: boolean;
+                resetPassword: boolean;
+                updatedAt: string;
+                access: string[];
+            }, {
+                type: string;
+                name: string;
+                createdAt: string;
+                id: string;
+                profileId: string;
+                identity: string;
+                roleId: string;
+                isActive: boolean;
+                isArchived: boolean;
+                resetPassword: boolean;
+                updatedAt: string;
+                access: string[];
+            }>;
+        };
+    };
+};