https://github.com/tellesy/fcms-client
Kotlin/Java SDK for FCMS APIs — fast, lightweight, no Spring.
https://github.com/tellesy/fcms-client
banking fintech fintech-api libya
Last synced: 5 months ago
JSON representation
Kotlin/Java SDK for FCMS APIs — fast, lightweight, no Spring.
- Host: GitHub
- URL: https://github.com/tellesy/fcms-client
- Owner: Tellesy
- License: other
- Created: 2025-08-23T18:13:38.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-12-03T15:33:35.000Z (7 months ago)
- Last Synced: 2025-12-06T12:34:41.190Z (7 months ago)
- Topics: banking, fintech, fintech-api, libya
- Language: Kotlin
- Homepage: https://tellesy.dev
- Size: 138 KB
- Stars: 5
- Watchers: 0
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# FCMS Client (Kotlin/Java SDK)
[](https://central.sonatype.com/artifact/io.github.tellesy/fcms-client)
A small, dependency-light JVM SDK for FCMS APIs (Salaries, Accounts, Requests). Works in any Kotlin or Java app (no Spring dependency). Optimized for performance and correctness.
- Group: `io.github.tellesy`
- Artifact: `fcms-client`
- Version: `1.0.4`
- JVM: Java 21+
## What's New in 1.0.4
- Entity model: `name` is now nullable (`String?`) to gracefully handle nulls from the API.
- Verified null-safe deserialization across optional fields (e.g., `bankAccount.bankBranch`, `transaction.description`).
- No breaking API changes; this is a robustness update.
## Supported Endpoints
- GET `{baseUrl}/api/v1/mof/transactions` → `Page`
- GET `{baseUrl}/api/v1/mof/transactions/{uuid}` → `Transaction`
- POST `{baseUrl}/api/v1/mof/transactions/{uuid}/complete` → `Transaction`
- POST `{baseUrl}/api/v1/mof/transactions/{uuid}/reject` → `Transaction`
- GET `{baseUrl}/api/v1/misc/mof/rejection-reasons` → `List`
- GET `{baseUrl}/api/v1/bank-accounts` → `Page` (supports filters via `AccountsListFilter`)
- PATCH `{baseUrl}/api/v1/bank-accounts/{uuid}/match` → `BankAccount`
- PATCH `{baseUrl}/api/v1/bank-accounts/{uuid}/reject` → `BankAccount`
- PATCH `{baseUrl}/api/v1/bank-accounts/{uuid}/unreject` → `BankAccount`
- PATCH `{baseUrl}/api/v1/bank-accounts/{uuid}/update` → `BankAccount`
- GET `{baseUrl}/api/v1/purchase-requests-queue` → `Page`
JSON is automatically unwrapped from envelopes like `{ "data": ... }`. Pagination is resilient to both Laravel shapes: root `links` object/array and `meta.links` arrays.
## Add Dependency
Gradle (Kotlin DSL):
```kotlin
repositories { mavenCentral() }
dependencies { implementation("io.github.tellesy:fcms-client:1.0.4") }
```
Maven:
```xml
io.github.tellesy
fcms-client
1.0.4
```
## Quick Start
Kotlin:
```kotlin
import ly.neptune.nexus.fcms.core.FcmsConfig
import ly.neptune.nexus.fcms.core.RequestOptions
import ly.neptune.nexus.fcms.salaries.*
import ly.neptune.nexus.fcms.salaries.model.request.CompleteTransactionRequest
import ly.neptune.nexus.fcms.accounts.*
import ly.neptune.nexus.fcms.requests.*
suspend fun main() {
val config = FcmsConfig(
baseUrl = System.getenv("FCMS_BASE_URL"),
tokenProvider = { System.getenv("FCMS_TOKEN") }
)
val salaries = FcmsSalariesClients.create(config)
val accounts = FcmsAccountsClients.create(config)
val requests = FcmsRequestsClients.create(config)
// Salaries
val page1 = salaries.listTransactions(page = 1)
// Typed filtering
val pending2025 = salaries.listTransactionsFiltered(
page = 1,
filter = SalariesListFilter(state = "pending", year = 2025)
)
val tx = salaries.showTransaction(
uuid = "8bb8fbde-21d7-4a37-99eb-fdce5294a1ee",
options = RequestOptions(
baseUrlOverride = "https://other-bank.example.com",
tokenOverride = "Bearer "
)
)
salaries.completeTransaction(
uuid = "569a715c-1053-4be7-acff-b65a8d915724",
request = CompleteTransactionRequest("BANK-REF-123", "1724232056")
)
// Accounts
val accountsPage = accounts.listAccounts(
page = 1,
filter = AccountsListFilter(state = "pending")
)
// Requests (pending purchase requests queue)
val queuePage = requests.listPendingRequests(page = 1)
}
```
Java:
```java
import ly.neptune.nexus.fcms.core.FcmsConfig;
import ly.neptune.nexus.fcms.core.RequestOptions;
import ly.neptune.nexus.fcms.salaries.*;
import ly.neptune.nexus.fcms.salaries.model.Page;
import ly.neptune.nexus.fcms.salaries.model.Transaction;
import ly.neptune.nexus.fcms.salaries.model.request.CompleteTransactionRequest;
public class Example {
public static void main(String[] args) throws Exception {
FcmsConfig config = new FcmsConfig(
System.getenv("FCMS_BASE_URL"),
() -> System.getenv("FCMS_TOKEN")
);
try (FcmsSalariesClientJava client = FcmsSalariesClientJava.create(config)) {
Page page = client.listTransactions(1, null).get();
// Typed filtering from Java
Page filtered = client
.listTransactions(1, new SalariesListFilter("pending", 2025, null), null)
.get();
Transaction t = client.showTransaction("8bb8fbde-21d7-4a37-99eb-fdce5294a1ee", null).get();
}
}
}
```
## Configuration
`FcmsConfig` sets global client defaults. `RequestOptions` allows per-call overrides:
- Base URL: `FcmsConfig.baseUrl` (override via `RequestOptions.baseUrlOverride`)
- Token: `FcmsConfig.tokenProvider` (override via `RequestOptions.tokenOverride`)
- Timeouts: connect/read/write timeouts globally; per-call read timeout via `RequestOptions.readTimeoutMillisOverride`
- Dispatcher concurrency: `maxRequests`, `maxRequestsPerHost`
- Retries: opt-in via `enableRetries`; only idempotent GETs retry by default; 429 Retry-After respected
## Error Handling
Non-2xx responses throw `ly.neptune.nexus.fcms.core.http.FcmsHttpException` with:
- `status` (HTTP)
- `code` and `message` (if available from body)
- `body` (raw)
- `headers` (map) and `retryAfterSeconds` (parsed if present)
## Pagination
List APIs return `Page` with fields: `data`, `total`, `perPage`, `currentPage`, `next`, `prev`. Examples:
- Salaries: `listTransactions(page)` → `Page`
- Accounts: `listAccounts(page, filter)` → `Page`
- Requests: `listPendingRequests(page)` → `Page`
- Laravel root links object `{ links: { next, prev } }` supported
- Laravel `meta.links` array supported
## Query parameters and filtering
The SDK builds URLs and query strings for you. Here’s how to pass filters safely:
- Salaries `GET {baseUrl}/api/v1/mof/transactions`
- Use `SalariesListFilter` with `listTransactionsFiltered(...)` to set Laravel-style filters:
Kotlin:
```kotlin
val salariesPage = salaries.listTransactionsFiltered(
page = 1,
filter = SalariesListFilter(
state = "pending", // -> filter[state]=pending
year = 2025, // -> filter[year]=2025
month = 8 // -> filter[month]=8
)
)
// Convenience helpers
val byState = salaries.listTransactionsByState("pending", page = 1)
val byYear = salaries.listTransactionsByYear(2025, page = 1)
val byYearMonth = salaries.listTransactionsByYearMonth(2025, 8, page = 1)
val byAll = salaries.listTransactionsByYearMonthState(2025, 8, "completed", page = 1)
// Raw map (advanced)
val raw = salaries.listTransactionsWithFilters(
page = 1,
filters = mapOf(
"filter[state]" to "pending",
"filter[year]" to "2025"
)
)
```
Java:
```java
// Typed filter
Page page = client
.listTransactions(1, new SalariesListFilter("pending", 2025, 8), null)
.get();
// Convenience wrappers
Page byState = client.listTransactionsByState("pending", 1, null).get();
Page byYear = client.listTransactionsByYear(2025, 1, null).get();
Page byYearMonth = client.listTransactionsByYearMonth(2025, 8, 1, null).get();
Page byAll = client.listTransactionsByYearMonthState(2025, 8, "completed", 1, null).get();
// Raw map
Page raw = client
.listTransactionsWithFilters(1, Map.of("filter[state]", "pending", "filter[year]", "2025"), null)
.get();
```
- Accounts `GET {baseUrl}/api/v1/bank-accounts`
- Use `AccountsListFilter` to set query params that map to Laravel-style filter keys:
Kotlin:
```kotlin
val accountsPage = accounts.listAccounts(
page = 1,
filter = AccountsListFilter(
state = "pending", // -> filter[state]=pending
iban = "SA123...", // -> filter[iban]=SA123...
createdOn = "2025-01-15", // -> filter[created_on]=2025-01-15
approvedOn = null, // omitted when null/blank
rejectedOn = null,
unrejectedOn = null,
accountNumber = null, // -> filter[account_number]=...
hasAccountNumber = true // -> filter[has_account_number]=true
)
)
```
Java:
```java
AccountsListFilter filter = new AccountsListFilter(
"pending", // state -> filter[state]=pending
null, // iban
null, // createdOn (yyyy-MM-dd)
null, // approvedOn
null, // rejectedOn
null, // unrejectedOn
null, // accountNumber
Boolean.TRUE // hasAccountNumber -> filter[has_account_number]=true
);
Page page = accountsClient.listAccounts(1, filter, null);
```
Notes:
- Only one question mark is used in a URL. Example with multiple filters: `...?filter[state]=pending&filter[year]=2025` (not `&?filter[year]=...`).
- Null/blank fields are omitted from the query string automatically.
## Salaries Data Models
The SDK maps Salaries API JSON into typed models. New fields added in 1.0.3 are marked; nullability updates in 1.0.4 are noted.
- Transaction
- `uuid: String`
- `state: String`
- `individual: Individual`
- `bankAccount: BankAccount`
- `salary: Salary`
- `entity: Entity?` (new in 1.0.3)
- `description: String?` (new in 1.0.3)
- Individual
- `name: String`, `nid: String`, `mofFinancialNumber: String`, `phoneNumber: String?`
- BankAccount
- `number: String`, `iban: String?`, `bankBranch: String?` (new in 1.0.3)
- Salary
- `amount: BigDecimal` (string or numeric in JSON supported)
- `currency: String`
- `period: Period { year: String, month: String }`
- Entity (new in 1.0.3)
- `name: String?` (nullable since 1.0.4), `region: String?`
Example (truncated):
```json
{
"uuid": "...",
"state": "pending",
"individual": { "name": "...", "nid": "...", "mofFinancialNumber": "..." },
"bankAccount": { "number": "...", "iban": "...", "bankBranch": "..." },
"salary": { "amount": "81834", "currency": "SAR", "period": { "year": "2025", "month": "08" } },
"entity": { "name": "...", "region": "..." },
"description": "..."
}
```
## Threading and Cleanup
- The client uses a single shared OkHttp `OkHttpClient` with HTTP/2, connection pooling, gzip.
- Suspend APIs are non-blocking; the Java facade uses `CompletableFuture`.
- Call `close()` when finished to allow resources to be released by GC.
## Build, Test, Docs
- Build & test: `./gradlew clean test`
- Generate docs: `./gradlew dokkaHtml` (output at `build/dokka/html`)
- Publish to Maven Local: `./gradlew publishToMavenLocal`
## Versioning
Semantic Versioning (SemVer). Breaking changes bump the major version.
## Examples
Quick usage examples are provided in the Quick Start (Kotlin/Java) sections above.
## Security
- Do not hardcode tokens or base URLs. Inject them via environment variables or your secret manager.
- Tests should use ephemeral tokens and never commit real credentials.
- Use per-call overrides with `RequestOptions` for multi-tenant scenarios instead of creating many clients.
## Using from Local Maven (for development)
If the artifact isn't in your remote repository yet, you can consume it locally:
1. In this repo: `./gradlew publishToMavenLocal`
2. In your app's Gradle config, add `mavenLocal()` before `mavenCentral()`:
```kotlin
repositories {
mavenLocal()
mavenCentral()
}
dependencies {
implementation("io.github.tellesy:fcms-client:1.0.4")
}
```
## License
Licensed under the [Apache License 2.0](LICENSE).
## Author
Muhammad Tellesy
Built by Muhammad Tellesy as part of the openNexus initiative.
```text
01100100 01100101 01101110 01101001 01100010 01101101 01101111 01100011 00100000 01100100 01100101 01110100 01101001 01101110 01101001 01100010 01101101 01101111 01100011 00100000 01101101 01100101 01101000 01110100 00100000 01100100 01101110 01100001 00100000 01110101 01101111 01111001 00100000 01110010 01100101 01100111 01110010 01100001 01101100 00100000 00101100 01001100 01000011 01000010 00100000 01110010 01110101 01101111 01111001 00100000 01101110 01100001 01101000 01110100 00100000 01110010 01100101 01100100 01101100 01110101 01101111 01101100 00100000 00101100 01100101 01110010 01100101 01101000 00100000 01101100 01101100 01101001 01110100 01110011 00100000 01101101 11100010 10000000 10011001 01001001 00100000 11100010 10000000 10010100 00100000 01110100 01101110 01100001 01110111 00100000 01110101 01101111 01111001 00100000 01100110 01101001 00100000 01111001 01100011 01100001 01100111 01100101 01001100 00100000 01111001 01101101 00100000 01100101 01110100 01100101 01101100 01100101 01000100 00001010
```