@temboplus/frontend-core 0.2.2 → 0.2.4

package/README.md

@@ -1,80 +1,134 @@
+```markdown
 # @temboplus/frontend-core
 
-A foundational JavaScript/TypeScript library that powers TemboPlus front-end applications. This library provides essential tools and data models that ensure consistency across all TemboPlus projects.
+A robust and versatile JavaScript/TypeScript library designed to streamline the development of TemboPlus front-end applications. This library provides a comprehensive suite of utilities, standardized data models, and services to ensure consistency, efficiency, and maintainability across all TemboPlus projects.
 
-## What's Inside
+## Core Features
 
-The library contains:
+* **Utility Functions:** A collection of pre-built helper functions to simplify common development tasks.
+* **Standardized Data Models:** Consistent and reliable data structures for managing essential data types, including phone numbers, amounts, currencies, countries, and bank details.
+* **Comprehensive Report Management:** A powerful `ReportManager` for generating and downloading reports in various formats across different TemboPlus projects.
+* **Centralized Configuration Service:** A flexible `ConfigService` for managing application settings and environment configurations.
 
-* **Utilities**: Ready-to-use helper functions for common development tasks
-* **Data Models**: Standardized structures for handling data like phone numbers, amounts, currencies, countries, and bank details
+## Data Models
 
-## Key Data Models
+This library offers a set of meticulously crafted data models, each designed to handle specific data types with precision:
 
-- **PhoneNumber**: International phone number handling with country-specific validation
-- **TZPhoneNumber**: Tanzania-specific phone number handling with network operator identification
-- **Amount**: Currency value handling with formatting and conversion
-- **Currency**: Comprehensive currency information with symbols, formatting rules, and validation
-- **Country**: Standardized country data with ISO codes and validation
-- **Bank**: Standardized bank account information management
+* **PhoneNumber:** Robust international phone number validation and formatting.
+* **TZPhoneNumber:** Specialized phone number handling for Tanzania, including network operator identification.
+* **Amount:** Precise currency value management, with support for formatting and conversion.
+* **Currency:** Detailed currency information, including symbols, formatting rules, and validation.
+* **Country:** Standardized country data with ISO codes and comprehensive validation.
+* **Bank:** Consistent bank account information management.
 
-## Working with Data Models
+## Report Management with `ReportManager`
 
-Each data model in our library comes with three key validation methods:
-
-### 1. Checking Object Types with `is`
+The `ReportManager` simplifies the process of generating and downloading reports across various TemboPlus projects.
 
 ```typescript
-if (PhoneNumber.is(someObject)) {
-    // someObject is a valid PhoneNumber
-    console.log(phoneNumber.label);
+import { ReportManager, FileFormat, ReportType, ProjectType } from '@temboplus/frontend-core';
+
+// Download a report
+async function downloadMerchantDisbursementReport() {
+    await ReportManager.instance.downloadReport({
+        token: "your-auth-token",
+        projectType: ProjectType.DASHBOARD,
+        reportType: ReportType.MERCHANT_DISBURSEMENT_REPORT,
+        fileFormat: FileFormat.PDF,
+        query: {
+            startDate: "2023-01-01T00:00:00.000Z",
+            endDate: "2023-01-31T00:00:00.000Z"
+        }
+    });
+}
+
+// Get all reports for a specific project
+import { getReportsByProject } from '@temboplus/frontend-core';
+function getAllDashboardReports(){
+  const dashboardReports = getReportsByProject(ProjectType.DASHBOARD);
+  return dashboardReports;
 }
 ```
 
-### 2. Validating Input Data with `canConstruct`
+### Supported Report Types
+
+* **Dashboard Reports:**
+    * `MERCHANT_DISBURSEMENT_REPORT`: Detailed merchant disbursement reports.
+    * `TRANSACTION_REVENUE_SUMMARY`: Revenue transaction summaries.
+* **Afloat Reports:**
+    * `CUSTOMER_WALLET_ACTIVITY`: Customer wallet activity logs.
+    * `CUSTOMER_PROFILE_SNAPSHOT`: Customer profile snapshots.
+* **VertoX Reports:**
+    * `GATEWAY_TRANSACTION_LOG`: Payment gateway transaction logs.
+
+## Configuration Service with `ConfigService`
+
+The `ConfigService` provides a centralized mechanism for managing application configurations.
 
 ```typescript
-if (Amount.canConstruct(userInput)) {
-    const amount = Amount.from(userInput);
-}
+import { ConfigService } from '@temboplus/frontend-core';
+
+// Initialize configuration at application startup
+ConfigService.instance.initialize({
+    pdfMakerBaseUrl: 'https://api.temboplus.com/pdf-maker' // Optional: Override default PDF maker base URL.
+});
 ```
 
-### 3. Verifying Instance Data with `validate`
+## Data Model Validation
+
+Each data model includes validation methods to ensure data integrity:
+
+* **`is(object)`:** Checks if an object is a valid instance of the data model.
+* **`canConstruct(input)`:** Validates input data before constructing a new instance.
+* **`validate()`:** Verifies the validity of an existing data model instance.
 
 ```typescript
+import { PhoneNumber, Amount } from '@temboplus/frontend-core';
+
+// Using is()
+if (PhoneNumber.is(someObject)) {
+    console.log(someObject.label);
+}
+
+// Using canConstruct()
+if (Amount.canConstruct(userInput)) {
+    const amount = Amount.from(userInput);
+}
+
+// Using validate()
 const phoneNumber = PhoneNumber.from("+1234567890");
 if (phoneNumber.validate()) {
-    processPhoneNumber(phoneNumber);
+    // Process the valid phone number.
 }
 ```
 
-## Static Access to Common Data
+## Static Data Access
 
-Many of our models provide convenient static access to common data:
+Convenient static properties are available for accessing common data:
 
 ```typescript
-// Access countries by ISO code or full name
+import { Country, Currency, Bank } from '@temboplus/frontend-core';
+
+// Country access
 const tanzania = Country.TZ;
 const usa = Country.UNITED_STATES;
 
-// Access currencies by code or full name
+// Currency access
 const usd = Currency.USD;
 const tzs = Currency.TANZANIAN_SHILLING;
 
-// Access banks by short name
+// Bank access
 const crdb = Bank.CRDB;
 const nmb = Bank.NMB;
 ```
 
-## Documentation
+## Detailed Model Documentation
 
-For detailed documentation on specific models:
-
-- [PhoneNumber Documentation](./docs/phone_number.md)
-- [Amount Documentation](./docs/amount.md)
-- [Bank Documentation](./docs/bank.md)
-- [Currency Documentation](./docs/currency.md)
-- [Country Documentation](./docs/country.md)
+* [PhoneNumber](./docs/phone_number.md)
+* [Amount](./docs/amount.md)
+* [Bank](./docs/bank.md)
+* [Currency](./docs/currency.md)
+* [Country](./docs/country.md)
 
 ## Installation
 
@@ -82,19 +136,17 @@ For detailed documentation on specific models:
 npm install @temboplus/frontend-core
 ```
 
-## Using Phone Numbers
-
-The library provides two phone number implementations:
+## Phone Number Usage
 
 ```typescript
 import { PhoneNumber, TZPhoneNumber, PhoneNumberFormat } from '@temboplus/frontend-core';
 
-// For international phone numbers:
-const phone = PhoneNumber.from("+1 (202) 555-0123");
-console.log(phone.getWithFormat(PhoneNumberFormat.INTERNATIONAL)); // +12025550123
+// International phone numbers
+const internationalPhone = PhoneNumber.from("+1 (202) 555-0123");
+console.log(internationalPhone.getWithFormat(PhoneNumberFormat.INTERNATIONAL)); // +12025550123
 
-// For Tanzania phone numbers:
-const tzPhone = TZPhoneNumber.from("0712345678");
-console.log(tzPhone.getWithFormat(PhoneNumberFormat.INTERNATIONAL)); // +255 712 345 678
-console.log(tzPhone.networkOperator.name); // "Vodacom"
-```
+// Tanzania phone numbers
+const tanzaniaPhone = TZPhoneNumber.from("0712345678");
+console.log(tanzaniaPhone.getWithFormat(PhoneNumberFormat.INTERNATIONAL)); // +255 712 345 678
+console.log(tanzaniaPhone.networkOperator.name); // "Yas"
+```

package/esm/mod.d.ts

@@ -1,3 +1,5 @@
 export * from "./src/models/index.js";
 export * from "./src/utils/index.js";
+export * from "./src/reports/index.js";
+export * from "./src/config/index.js";
 //# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC"}

package/esm/mod.js

@@ -1,2 +1,4 @@
 export * from "./src/models/index.js";
 export * from "./src/utils/index.js";
+export * from "./src/reports/index.js";
+export * from "./src/config/index.js";

package/esm/src/config/config_service.d.ts

@@ -0,0 +1,11 @@
+export declare class ConfigService {
+    private static _instance;
+    private _pdfMakerBaseUrl;
+    private constructor();
+    static get instance(): ConfigService;
+    initialize(config: {
+        pdfMakerBaseUrl: string;
+    }): void;
+    get pdfMakerBaseUrl(): string;
+}
+//# sourceMappingURL=config_service.d.ts.map

package/esm/src/config/config_service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config_service.d.ts","sourceRoot":"","sources":["../../../src/src/config/config_service.ts"],"names":[],"mappings":"AAAA,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,SAAS,CAAgB;IACxC,OAAO,CAAC,gBAAgB,CAAc;IAEtC,OAAO;IAEP,WAAkB,QAAQ,kBAEzB;IAEM,UAAU,CAAC,MAAM,EAAE;QAAE,eAAe,EAAE,MAAM,CAAA;KAAE;IAIrD,IAAW,eAAe,IAAI,MAAM,CAEnC;CACF"}

package/esm/src/config/config_service.js

@@ -0,0 +1,19 @@
+export class ConfigService {
+    constructor() {
+        Object.defineProperty(this, "_pdfMakerBaseUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ""
+        });
+    }
+    static get instance() {
+        return this._instance || (this._instance = new this());
+    }
+    initialize(config) {
+        this._pdfMakerBaseUrl = config.pdfMakerBaseUrl;
+    }
+    get pdfMakerBaseUrl() {
+        return this._pdfMakerBaseUrl;
+    }
+}

package/esm/src/config/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./config_service.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/src/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/config/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA"}

package/esm/src/config/index.js

@@ -0,0 +1 @@
+export * from "./config_service.js";

package/esm/src/models/phone_number/tz/network_operator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network_operator.d.ts","sourceRoot":"","sources":["../../../../../src/src/models/phone_number/tz/network_operator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,oBAAY,eAAe;IACzB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,EAAE,EAAE,eAAe,CAAC;IAEpB,+DAA+D;IAC/D,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAE/B,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IAEpB,wDAAwD;IACxD,kBAAkB,EAAE,MAAM,CAAC;IAE3B,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAC1C,eAAe,EACf,mBAAmB,CA8BpB,CAAC"}
+{"version":3,"file":"network_operator.d.ts","sourceRoot":"","sources":["../../../../../src/src/models/phone_number/tz/network_operator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,oBAAY,eAAe;IACzB,OAAO,YAAY;IACnB,MAAM,WAAW;IAIjB,IAAI,SAAS;IACb,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,EAAE,EAAE,eAAe,CAAC;IAEpB,+DAA+D;IAC/D,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAE/B,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IAEpB,wDAAwD;IACxD,kBAAkB,EAAE,MAAM,CAAC;IAE3B,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAC1C,eAAe,EACf,mBAAmB,CA8BpB,CAAC"}

package/esm/src/models/phone_number/tz/network_operator.js

@@ -6,6 +6,9 @@ export var NetworkOperator;
 (function (NetworkOperator) {
     NetworkOperator["VODACOM"] = "Vodacom";
     NetworkOperator["AIRTEL"] = "Airtel";
+    // Preserve the value "Tigo" bse our backend still recognizes it for payout channel codes
+    // It should not be seen anywhere for we have NetworkOperatorInfo.displayName & NetworkOperatorInfo.mobileMoneyService
+    // as labels we can use on the frontend
     NetworkOperator["TIGO"] = "Tigo";
     NetworkOperator["HALOTEL"] = "Halotel";
 })(NetworkOperator || (NetworkOperator = {}));
@@ -31,8 +34,8 @@ export const NETWORK_OPERATOR_CONFIG = {
         id: NetworkOperator.TIGO,
         mobileNumberPrefixes: ["71", "65", "67", "77"],
         displayName: "Yas",
-        mobileMoneyService: "Mixx",
-        brandColor: "blue",
+        mobileMoneyService: "Mixx by Yas",
+        brandColor: "yellow",
     },
     [NetworkOperator.HALOTEL]: {
         id: NetworkOperator.HALOTEL,

package/esm/src/reports/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./report_manager.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/src/reports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/reports/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA"}

package/esm/src/reports/index.js

@@ -0,0 +1 @@
+export * from "./report_manager.js";

package/esm/src/reports/report_manager.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Available file formats for reports
+ */
+export declare enum FileFormat {
+    /** PDF file format */
+    PDF = "pdf",
+    /** Excel file format */
+    EXCEL = "excel"
+}
+/**
+ * Available project types
+ */
+export declare enum ProjectType {
+    /** Tembo Dashboard project */
+    DASHBOARD = "dashboard",
+    /** Afloat project */
+    AFLOAT = "afloat",
+    /** VertoX project */
+    VERTO_X = "verto_x"
+}
+/**
+ * Available report types with improved naming
+ */
+export declare enum ReportType {
+    /** Merchant payout statement (Dashboard) */
+    MERCHANT_DISBURSEMENT_REPORT = "merchant_disbursement_report",
+    /** Transaction revenue summary (Dashboard) */
+    TRANSACTION_REVENUE_SUMMARY = "transaction_revenue_summary",
+    /** Customer wallet activity (Afloat) */
+    CUSTOMER_WALLET_ACTIVITY = "customer_wallet_activity",
+    /** Customer profile information (Afloat) */
+    CUSTOMER_PROFILE_SNAPSHOT = "customer_profile_snapshot",
+    /** Gateway transaction log (VertoX) */
+    GATEWAY_TRANSACTION_LOG = "gateway_transaction_log"
+}
+/**
+ * Report definition interface
+ */
+export interface ReportDefinition {
+    /** Unique identifier for the report */
+    id: string;
+    /** Human-readable report name for UI display */
+    displayName: string;
+    /** API endpoint path for the report */
+    endpoint: string;
+    /** Available file formats for the report */
+    availableFormats: FileFormat[];
+    /** Optional description of the report */
+    description?: string;
+    /** Project the report belongs to */
+    projectType: ProjectType;
+    /** Type of the report */
+    reportType: ReportType;
+}
+/**
+ * Registry of all available reports
+ */
+export declare const REPORTS: {
+    merchant_disbursement_report: ReportDefinition;
+    transaction_revenue_summary: ReportDefinition;
+    customer_wallet_activity: ReportDefinition;
+    customer_profile_snapshot: ReportDefinition;
+    gateway_transaction_log: ReportDefinition;
+};
+/**
+ * Get all reports for a specific project
+ * @param projectType The project type to filter by
+ * @returns Array of report definitions for the project
+ */
+export declare function getReportsByProject(projectType: ProjectType): ReportDefinition[];
+/**
+ * Get a report by its type
+ * @param reportType The report type to retrieve
+ * @returns The report definition or undefined if not found
+ */
+export declare function getReportByType(reportType: ReportType): ReportDefinition;
+/**
+ * Validates if a report type is available for a project
+ * @param projectType The project type
+ * @param reportType The report type
+ * @returns True if the report is available for the project, false otherwise
+ */
+export declare function isReportAvailableForProject(projectType: ProjectType, reportType: ReportType): boolean;
+/**
+ * Report Manager class for handling report downloads
+ */
+export declare class ReportManager {
+    private static _instance;
+    private constructor();
+    /**
+     * Get the singleton instance of ReportManager
+     */
+    static get instance(): ReportManager;
+    /**
+     * Get the base URL for the report API
+     * @returns The base URL
+     */
+    private getBaseURL;
+    /**
+     * Downloads a report based on project type and report type
+     * @param args Arguments for the report download
+     * @returns Promise that resolves when download is complete
+     */
+    downloadReport(args: {
+        token: string;
+        projectType: ProjectType;
+        reportType: ReportType;
+        fileFormat: FileFormat;
+        query?: Record<string, any>;
+    }): Promise<void>;
+    /**
+     * Process the download
+     * @param response The response from the API
+     * @param report The report definition
+     * @param fileFormat The requested file format
+     */
+    private processDownload;
+    /**
+     * Handle error responses from the API
+     * @param response The response from the API
+     * @throws Error with appropriate message
+     */
+    private handleErrorResponse;
+    /**
+     * Generates a default filename based on report and file format
+     * @param report The report definition
+     * @param fileFormat The requested file format
+     * @returns A suitable default filename with proper extension
+     */
+    private getDefaultFilename;
+    /**
+     * Extracts the filename from the Content-Disposition header
+     * @param contentDisposition The Content-Disposition header value
+     * @returns The extracted filename or null if not found
+     */
+    private extractFilenameFromContentDisposition;
+    /**
+     * Converts a base64 string to a Blob
+     * @param base64 The base64 string
+     * @returns A Blob
+     */
+    private b64toBlob;
+}
+//# sourceMappingURL=report_manager.d.ts.map

package/esm/src/reports/report_manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report_manager.d.ts","sourceRoot":"","sources":["../../../src/src/reports/report_manager.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,oBAAY,UAAU;IACpB,sBAAsB;IACtB,GAAG,QAAQ;IACX,wBAAwB;IACxB,KAAK,UAAU;CAChB;AAED;;GAEG;AACH,oBAAY,WAAW;IACrB,8BAA8B;IAC9B,SAAS,cAAc;IACvB,qBAAqB;IACrB,MAAM,WAAW;IACjB,qBAAqB;IACrB,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,oBAAY,UAAU;IACpB,4CAA4C;IAC5C,4BAA4B,iCAAiC;IAC7D,8CAA8C;IAC9C,2BAA2B,gCAAgC;IAC3D,wCAAwC;IACxC,wBAAwB,6BAA6B;IACrD,4CAA4C;IAC5C,yBAAyB,8BAA8B;IACvD,uCAAuC;IACvC,uBAAuB,4BAA4B;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,gBAAgB,EAAE,UAAU,EAAE,CAAC;IAC/B,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,WAAW,EAAE,WAAW,CAAC;IACzB,yBAAyB;IACzB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;;GAEG;AACH,eAAO,MAAM,OAAO;kCAUb,gBAAgB;iCAUhB,gBAAgB;8BAWhB,gBAAgB;+BAUhB,gBAAgB;6BAWhB,gBAAgB;CACtB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,WAAW,GACvB,gBAAgB,EAAE,CAIpB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,gBAAgB,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,WAAW,EACxB,UAAU,EAAE,UAAU,GACrB,OAAO,CAGT;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,SAAS,CAAgB;IAExC,OAAO;IAEP;;OAEG;IACH,WAAkB,QAAQ,kBAEzB;IAED;;;OAGG;IACH,OAAO,CAAC,UAAU,CAOhB;IAEF;;;;OAIG;IACU,cAAc,CAAC,IAAI,EAAE;QAChC,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,WAAW,CAAC;QACzB,UAAU,EAAE,UAAU,CAAC;QACvB,UAAU,EAAE,UAAU,CAAC;QAEvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC7B,GAAG,OAAO,CAAC,IAAI,CAAC;IAmFjB;;;;;OAKG;YACW,eAAe;IAqB7B;;;;OAIG;YACW,mBAAmB;IAwBjC;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAe1B;;;;OAIG;IACH,OAAO,CAAC,qCAAqC;IA6B7C;;;;OAIG;IACH,OAAO,CAAC,SAAS,CACyB;CAC3C"}