{"id":24394415,"url":"https://github.com/temboplus-frontend/frontend-core-js","last_synced_at":"2025-04-11T13:43:45.169Z","repository":{"id":271712654,"uuid":"908979802","full_name":"TemboPlus-Frontend/frontend-core-js","owner":"TemboPlus-Frontend","description":"A JavaScript/TypeScript package providing common utilities and logic shared across all front-end TemboPlus projects.","archived":false,"fork":false,"pushed_at":"2025-03-28T06:20:51.000Z","size":1129,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-04-04T08:38:46.314Z","etag":null,"topics":["deno","package"],"latest_commit_sha":null,"homepage":"https://jsr.io/@temboplus/tembo-core","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TemboPlus-Frontend.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-27T12:53:57.000Z","updated_at":"2025-03-28T06:20:54.000Z","dependencies_parsed_at":"2025-02-27T13:51:10.714Z","dependency_job_id":"8b3bf95f-d7d8-4942-9c56-dc683f2539ac","html_url":"https://github.com/TemboPlus-Frontend/frontend-core-js","commit_stats":null,"previous_names":["temboplus-frontend/tembo_core_js","temboplus-frontend/frontend-core-js"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TemboPlus-Frontend%2Ffrontend-core-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TemboPlus-Frontend%2Ffrontend-core-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TemboPlus-Frontend%2Ffrontend-core-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TemboPlus-Frontend%2Ffrontend-core-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TemboPlus-Frontend","download_url":"https://codeload.github.com/TemboPlus-Frontend/frontend-core-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248410877,"owners_count":21098789,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deno","package"],"created_at":"2025-01-19T19:24:19.350Z","updated_at":"2025-04-11T13:43:45.160Z","avatar_url":"https://github.com/TemboPlus-Frontend.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @temboplus/frontend-core\n\nA 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.\n\n## Core Features\n\n* **Utility Functions:** A collection of pre-built helper functions to simplify common development tasks.\n* **Standardized Data Models:** Consistent and reliable data structures for managing essential data types, including phone numbers, amounts, currencies, countries, and bank details.\n* **Comprehensive Report Management:** A powerful `ReportManager` for generating and downloading reports in various formats across different TemboPlus projects.\n* **Centralized Configuration Service:** A flexible `ConfigService` for managing application settings and environment configurations.\n\n## Data Models\n\nThis library offers a set of meticulously crafted data models, each designed to handle specific data types with precision:\n\n* **PhoneNumber:** Robust international phone number validation and formatting.\n* **TZPhoneNumber:** Specialized phone number handling for Tanzania, including network operator identification.\n* **Amount:** Precise currency value management, with support for formatting and conversion.\n* **Currency:** Detailed currency information, including symbols, formatting rules, and validation.\n* **Country:** Enhanced country data handling with ISO-2 and ISO-3 codes, official names, flag emojis, and strongly-typed geographical categorization.\n* **Bank:** Consistent bank account information management.\n\n## Report Management with `ReportManager`\n\nThe `ReportManager` simplifies the process of generating and downloading reports across various TemboPlus projects.\n\n```typescript\nimport { ReportManager, FileFormat, ReportType, ProjectType } from '@temboplus/frontend-core';\n\n// Download a report\nasync function downloadMerchantDisbursementReport() {\n    await ReportManager.instance.downloadReport({\n        token: \"your-auth-token\",\n        projectType: ProjectType.DASHBOARD,\n        reportType: ReportType.MERCHANT_DISBURSEMENT_REPORT,\n        fileFormat: FileFormat.PDF,\n        query: {\n            startDate: \"2023-01-01T00:00:00.000Z\",\n            endDate: \"2023-01-31T00:00:00.000Z\"\n        }\n    });\n}\n\n// Get all reports for a specific project\nimport { getReportsByProject } from '@temboplus/frontend-core';\nfunction getAllDashboardReports(){\n  const dashboardReports = getReportsByProject(ProjectType.DASHBOARD);\n  return dashboardReports;\n}\n```\n\n### Supported Report Types\n\n* **Dashboard Reports:**\n    * `MERCHANT_DISBURSEMENT_REPORT`: Detailed merchant disbursement reports.\n    * `TRANSACTION_REVENUE_SUMMARY`: Revenue transaction summaries.\n* **Afloat Reports:**\n    * `CUSTOMER_WALLET_ACTIVITY`: Customer wallet activity logs.\n    * `CUSTOMER_PROFILE_SNAPSHOT`: Customer profile snapshots.\n* **VertoX Reports:**\n    * `GATEWAY_TRANSACTION_LOG`: Payment gateway transaction logs.\n\n## Configuration Service with `ConfigService`\n\nThe `ConfigService` provides a centralized mechanism for managing application configurations.\n\n```typescript\nimport { ConfigService } from '@temboplus/frontend-core';\n\n// Initialize configuration at application startup\nConfigService.instance.initialize({\n    pdfMakerBaseUrl: 'http://localhost:3000' // Optional: Override default PDF maker base URL.\n});\n```\n\n## Data Model Validation\n\nEach data model includes validation methods to ensure data integrity:\n\n* **`is(object)`:** Checks if an object is a valid instance of the data model.\n* **`canConstruct(input)`:** Validates input data before constructing a new instance.\n* **`validate()`:** Verifies the validity of an existing data model instance.\n\n```typescript\nimport { PhoneNumber, Amount } from '@temboplus/frontend-core';\n\n// Using is()\nif (PhoneNumber.is(someObject)) {\n    console.log(someObject.label);\n}\n\n// Using canConstruct()\nif (Amount.canConstruct(userInput)) {\n    const amount = Amount.from(userInput);\n}\n\n// Using validate()\nconst phoneNumber = PhoneNumber.from(\"+1234567890\");\nif (phoneNumber.validate()) {\n    // Process the valid phone number.\n}\n```\n\n## Type-Safe String Literals\n\nThis library provides strongly-typed string literals for standardized codes:\n\n* **Country Codes:**\n  * `ISO2CountryCode`: Two-letter country codes (e.g., \"US\", \"GB\", \"DE\")\n  * `ISO3CountryCode`: Three-letter country codes (e.g., \"USA\", \"GBR\", \"DEU\")\n  * `CountryCode`: A union type that accepts either ISO-2 or ISO-3 formats\n\n* **Currency Codes:**\n  * `CurrencyCode`: Three-letter currency codes (e.g., \"USD\", \"EUR\", \"JPY\")\n\nThese types provide compile-time validation and auto-completion while having zero runtime overhead:\n\n```typescript\nimport { \n  ISO2CountryCode, \n  ISO3CountryCode, \n  CountryCode, \n  CurrencyCode \n} from '@temboplus/frontend-core';\n\n// Type-safe function parameters\nfunction processTransaction(\n  amount: number,\n  currency: CurrencyCode,\n  country: CountryCode\n) {\n  // Implementation\n}\n\n// Valid calls - compile-time checking ensures only valid codes are accepted\nprocessTransaction(100, \"USD\", \"US\");   // ISO-2 country code\nprocessTransaction(200, \"EUR\", \"DEU\");  // ISO-3 country code\n\n// Invalid calls - caught by TypeScript at compile time\nprocessTransaction(300, \"XYZ\", \"US\");   // Error: \"XYZ\" is not a valid CurrencyCode\nprocessTransaction(400, \"USD\", \"ZZZ\");  // Error: \"ZZZ\" is not a valid CountryCode\n```\n\n## Static Data Access\n\nConvenient static properties are available for accessing common data:\n\n```typescript\nimport { Country, Currency, Bank, CONTINENT, SUB_REGION } from '@temboplus/frontend-core';\n\n// Country access with enhanced features\nconst tanzania = Country.TZ;\nconsole.log(tanzania.flagEmoji); // 🇹🇿\nconsole.log(tanzania.continent); // CONTINENT.AFRICA\nconsole.log(tanzania.region); // SUB_REGION.EASTERN_AFRICA\n\n// Regional country grouping with type-safe enums\nconst africanCountries = Country.getByContinent(CONTINENT.AFRICA);\nconst caribbeanCountries = Country.getByRegion(SUB_REGION.CARIBBEAN);\n\n// Currency access\nconst usd = Currency.USD;\nconst tzs = Currency.TANZANIAN_SHILLING;\n\n// Access country's currency\nconst japan = Country.JP;\nconst yen = japan.getCurrency();\nconsole.log(yen?.code); // \"JPY\"\n\n// Find countries using a specific currency\nconst euroCountries = Country.getByCurrencyCode(\"EUR\");\nconsole.log(`${euroCountries.length} countries use the Euro`);\n\n// Bank access\nconst crdb = Bank.CRDB;\nconst nmb = Bank.NMB;\n```\n\n## Phone Number Usage\n\n```typescript\nimport { PhoneNumber, TZPhoneNumber, PhoneNumberFormat } from '@temboplus/frontend-core';\n\n// International phone numbers\nconst internationalPhone = PhoneNumber.from(\"+1 (202) 555-0123\");\nconsole.log(internationalPhone.getWithFormat(PhoneNumberFormat.INTERNATIONAL)); // +12025550123\n\n// Tanzania phone numbers\nconst tanzaniaPhone = TZPhoneNumber.from(\"0712345678\");\nconsole.log(tanzaniaPhone.getWithFormat(PhoneNumberFormat.INTERNATIONAL)); // +255 712 345 678\nconsole.log(tanzaniaPhone.networkOperator.name); // \"Yas\"\n```\n\n## Detailed Model Documentation\n\n* [PhoneNumber](./docs/phone_number.md)\n* [Amount](./docs/amount.md)\n* [Bank](./docs/bank.md)\n* [Currency](./docs/currency.md)\n* [Country](./docs/country.md)\n\n## Installation\n\n```bash\nnpm install @temboplus/frontend-core\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftemboplus-frontend%2Ffrontend-core-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftemboplus-frontend%2Ffrontend-core-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftemboplus-frontend%2Ffrontend-core-js/lists"}