@ixo/supamoto-bot-sdk
Version:
An SDK to easily interact with Supamoto bot db
1,087 lines (872 loc) • 29.7 kB
Markdown
# IXO SUPAMOTO BOT SDK
[](https://ixo.foundation)
[](https://github.com/ixofoundation/ixo-matrixclient-sdk)
[](https://github.com/ixofoundation/ixo-matrixclient-sdk/blob/main/LICENSE)
[](https://twitter.com/ixoworld)
[](https://ixoworld.medium.com/)
<br />
<h2 align="center">
A TypeScript SDK for Supamoto Bot Database Operations
</h2>
<br />
The IXO Supamoto Bot SDK provides a comprehensive set of database operations for managing customer data, claims, credentials, and other entities in the Supamoto ecosystem. Built with TypeScript and PostgreSQL, it offers type-safe database interactions with built-in utilities for validation, encryption, and indexing.
## Table of Contents
- [IXO SUPAMOTO BOT SDK](#ixo-supamoto-bot-sdk)
- [Table of Contents](#table-of-contents)
- [Installation](#installation)
- [Getting Started](#getting-started)
- [API Client](#api-client)
- [Claims API](#claims-api)
- [Collection IDs API](#collection-ids-api)
- [Customers API](#customers-api)
- [Override Parameters](#override-parameters)
- [Claims Bot Client](#claims-bot-client)
- [Claims Submission](#claims-submission)
- [Onboarding Fee Claims](#onboarding-fee-claims)
- [Fuel Purchase Claims](#fuel-purchase-claims)
- [Fuel Delivery Claims](#fuel-delivery-claims)
- [1000-Day Household Claims](#1000-day-household-claims)
- [Collection IDs Management](#collection-ids-management)
- [Supported Enums](#supported-enums)
- [Response Types](#response-types)
- [Error Handling](#error-handling)
- [Database Client](#database-client)
- [Connection Pool Configuration](#connection-pool-configuration)
- [Transactions](#transactions)
- [Database Operations](#database-operations)
- [Customers](#customers)
- [Phones](#phones)
- [Customer Phones](#customer-phones)
- [Claims](#claims)
- [Customer Credentials](#customer-credentials)
- [Customer Onboardings](#customer-onboardings)
- [Household Entities](#household-entities)
- [Household Credentials](#household-credentials)
- [IXO Accounts](#ixo-accounts)
- [Matrix Accounts](#matrix-accounts)
- [Config](#config)
- [Claim Issues](#claim-issues)
- [Utilities](#utilities)
- [Validators](#validators)
- [Encryption](#encryption)
- [Indexing](#indexing)
- [Claims Utilities](#claims-utilities)
- [Customers Utilities](#customers-utilities)
- [Type Definitions](#type-definitions)
- [Error Handling](#error-handling-1)
- [Contributing](#contributing)
- [License](#license)
- [Support](#support)
## Installation
To install the SDK, add it to your project using npm or yarn:
```bash
npm install @ixo/supamoto-bot-sdk
```
or
```bash
yarn add @ixo/supamoto-bot-sdk
```
## Getting Started
Once installed, import the SDK components into your project:
```typescript
import { createDatabaseClient, createApiClient, utils } from '@ixo/supamoto-bot-sdk';
import type { IClaim, ICustomer, IPhone, ... } from '@ixo/supamoto-bot-sdk';
```
## API Client
The SDK provides an API client for interacting with the Supamoto Bot API endpoints. Create an API client by providing the bot URL and access token:
```typescript
import { createApiClient } from '@ixo/supamoto-bot-sdk';
const api = createApiClient({
botUrl: 'https://your-bot-url.com',
accessToken: 'your-access-token',
});
```
### Claims API
Manage claims through the API:
```typescript
// Get a specific claim
const claim = await api.claims.v1.getClaim({
claimId: 'claim-123',
collectionId: 'collection-123',
});
// Save a new claim
const savedClaim = await api.claims.v1.saveClaim({
collectionId: 'collection-123',
claim: '{"data": "claim-data"}',
});
// Get claims by collection
const collectionClaims = await api.claims.v1.getCollectionClaims({
collectionId: 'collection-123',
});
// Get claims by multiple collections
const multipleCollectionClaims = await api.claims.v1.getCollectionClaims({
collectionIds: ['collection-123', 'collection-456'],
});
// Get claims by customer
const customerClaims = await api.claims.v1.getCustomerClaims({
customerId: 'C123',
});
// Get claims by multiple customers
const multipleCustomerClaims = await api.claims.v1.getCustomerClaims({
customerIds: ['C123', 'customer-456'],
});
```
### Collection IDs API
Manage collection ID mappings:
```typescript
// Get all collection IDs
const collectionIds = await api.collectionIds.v1.getCollectionIds();
// Get a specific collection ID by key
const collectionId = await api.collectionIds.v1.getCollectionId({
collectionKey: 'lead', // or 'screening', 'contract', etc.
});
// Set a collection ID for a key
const setResult = await api.collectionIds.v1.setCollectionId({
collectionKey: 'lead',
collectionId: 'collection-123',
});
```
### Customers API
Search and retrieve customer data:
```typescript
// Search customers with filters
const searchResults = await api.customers.v1.searchCustomers({
queue: 'screening',
search: 'John',
country: 'ZM',
queued: true,
limit: 10,
offset: 0,
});
// Get a specific customer
const customer = await api.customers.v1.getCustomer({
customerId: 'C123',
});
// Get multiple customers
const customers = await api.customers.v1.getCustomers({
customerIds: ['C123', 'customer-456'],
});
```
### Override Parameters
All API methods support optional override parameters for bot URL and access token:
```typescript
// Use different credentials for a specific call
const claim = await api.claims.v1.getClaim(
{
claimId: 'claim-123',
collectionId: 'collection-123',
},
'https://different-bot-url.com', // Override bot URL
'different-access-token', // Override access token
);
```
## Claims Bot Client
The SDK provides a specialized claims bot client for submitting various types of claims to the Supamoto Bot system. Create a claims bot client by providing the bot URL and access token:
```typescript
import { createClaimsBotClient } from '@ixo/supamoto-bot-sdk';
const claimsBot = createClaimsBotClient({
botUrl: 'https://your-bot-url.com',
accessToken: 'your-access-token',
});
```
### Claims Submission
Submit different types of claims through the claims bot:
#### Onboarding Fee Claims
Submit claims for customer onboarding fees:
```typescript
const onboardingFeeClaim = await claimsBot.claims.v1.submitOnboardingFeeClaim({
customerId: 'C123', // Optional if did is provided
did: 'did:ixo:123', // Optional if customerId is provided
country: 'ZM', // Optional: 'ZM' for Zambia, 'MW' for Malawi
currency: 'ZMW', // 'ZMW' for Zambian Kwacha, 'MWK' for Malawian Kwacha
amount: 50.0,
transactionId: 'txn-123456',
method: 'mobile_money', // Optional payment method
provider: 'mtn', // 'mtn', 'zamtel', 'tnm', or 'airtel'
transactionDate: '2024-01-15T10:30:00Z',
});
```
#### Fuel Purchase Claims
Submit claims for fuel purchases:
```typescript
const fuelPurchaseClaim = await claimsBot.claims.v1.submitFuelPurchaseClaim({
customerId: 'C123',
did: 'did:ixo:123',
country: 'ZM',
currency: 'ZMW',
amount: 25.5,
product: 'Diesel',
quantity: '5 liters',
transactionId: 'txn-789012',
method: 'mobile_money',
provider: 'airtel',
transactionDate: '2024-01-15T14:20:00Z',
});
```
#### Fuel Delivery Claims
Submit claims for fuel deliveries (uses the same interface as fuel purchase):
```typescript
const fuelDeliveryClaim = await claimsBot.claims.v1.submitFuelDeliveryClaim({
customerId: 'C123',
did: 'did:ixo:123',
country: 'ZM',
currency: 'ZMW',
amount: 30.0,
product: 'Petrol',
quantity: '6 liters',
transactionId: 'txn-345678',
method: 'mobile_money',
provider: 'zamtel',
transactionDate: '2024-01-15T16:45:00Z',
});
```
#### 1000-Day Household Claims
Submit claims for 1000-day-household program:
```typescript
const householdClaim = await claimsBot.claims.v1.submit1000DayHouseholdClaim({
customerId: 'C123', // Required
beneficiaryCategory: BeneficiaryCategory.pregnant, // Required: 'Pregnant Woman', 'Breastfeeding Woman', 'Chile Below 2 Years'
childMaxAge: 18, // Required: Maximum age of child in months
beanIntakeFrequency: BeanIntakeFrequency.daily, // Required: 'None at all', '1-2 times a week', '3-4 times a week', '5-6 times a week', 'Daily'
priceSpecification: '5 ZMW', // Required: Price specification
awarenessIronBeans: AwarenessIronBeans.yes, // Required: 'Yes' or 'No'
knowsNutritionalBenefits: KnowsNutritionalBenefits.yes, // Required: 'Yes' or 'No'
nutritionalBenefitsDetails: NutritionalBenefitsDetails.ironStatus, // Required: 'iron_status', 'cognitive_support', 'work_capacity', 'high_iron_zinc', 'protein_fiber'
antenatalCardVerified: true, // Required: Boolean indicating if antenatal card is verified
});
```
### Collection IDs Management
Retrieve collection ID mappings for different claim types:
```typescript
// Get all collection IDs
const allCollectionIds = await claimsBot.collectionIds.v1.getCollectionIds();
// Returns: { lead, screening, contract, onboardingFee, homeVisit, fuelPurchase, bagStove }
// Get a specific collection ID
const onboardingFeeCollectionId = await claimsBot.collectionIds.v1.getCollectionId({
collectionKey: 'onboardingFee', // 'lead', 'screening', 'contract', 'onboardingFee', 'homeVisit', 'fuelPurchase', 'bagStove', '1000DayHousehold'
});
```
### Supported Enums
The claims bot client supports several enums for type safety:
```typescript
import {
Country,
Currency,
PaymentProvider,
BeneficiaryCategory,
BeanIntakeFrequency,
AwarenessIronBeans,
KnowsNutritionalBenefits,
NutritionalBenefitsDetails,
} from '@ixo/supamoto-bot-sdk';
// Countries
Country.Zambia; // 'ZM'
Country.Malawi; // 'MW'
// Currencies
Currency.ZambianKwacha; // 'ZMW'
Currency.MalawianKwacha; // 'MWK'
// Payment Providers
PaymentProvider.MTN; // 'mtn'
PaymentProvider.ZAMTEL; // 'zamtel'
PaymentProvider.TNM; // 'tnm'
PaymentProvider.AIRTEL; // 'airtel'
// Beneficiary Categories (for 1000-day household claims)
BeneficiaryCategory.pregnant; // 'Pregnant Woman'
BeneficiaryCategory.breastfeeding; // 'Breastfeeding Woman'
BeneficiaryCategory.child; // 'Chile Below 2 Years'
// Bean Intake Frequency
BeanIntakeFrequency.none; // 'None at all'
BeanIntakeFrequency.oneOrTwo; // '1-2 times a week'
BeanIntakeFrequency.threeOrFour; // '3-4 times a week'
BeanIntakeFrequency.fiveOrSize; // '5-6 times a week'
BeanIntakeFrequency.daily; // 'Daily'
// Awareness Iron Beans
AwarenessIronBeans.yes; // 'Yes'
AwarenessIronBeans.no; // 'No'
// Knows Nutritional Benefits
KnowsNutritionalBenefits.yes; // 'Yes'
KnowsNutritionalBenefits.no; // 'No'
// Nutritional Benefits Details
NutritionalBenefitsDetails.ironStatus; // 'iron_status'
NutritionalBenefitsDetails.cognitiveSupport; // 'cognitive_support'
NutritionalBenefitsDetails.workCapacity; // 'work_capacity'
NutritionalBenefitsDetails.highIronZinc; // 'high_iron_zinc'
NutritionalBenefitsDetails.protein_fiber; // 'protein_fiber'
```
### Response Types
All claim submission methods return a response with the generated claim ID:
```typescript
interface ClaimSubmissionResponse {
data: {
claimId: string;
};
}
```
### Error Handling
The claims bot client throws exceptions for API errors. Always wrap operations in try-catch blocks:
```typescript
try {
const claim = await claimsBot.claims.v1.submit1000DayHouseholdClaim({
customerId: 'C123',
beneficiaryCategory: BeneficiaryCategory.pregnant,
childMaxAge: 18,
beanIntakeFrequency: BeanIntakeFrequency.daily,
priceSpecification: 'Standard pricing',
awarenessIronBeans: AwarenessIronBeans.yes,
knowsNutritionalBenefits: KnowsNutritionalBenefits.yes,
nutritionalBenefitsDetails: NutritionalBenefitsDetails.ironStatus,
antenatalCardVerified: true,
});
console.log('Claim submitted:', claim.data.claimId);
} catch (error) {
console.error('Claims bot error:', error);
// Handle the error appropriately
}
```
## Database Client
Create a database client by providing PostgreSQL connection parameters:
```typescript
import { createDatabaseClient } from '@ixo/supamoto-bot-sdk';
const db = createDatabaseClient({
user: 'your-username',
password: 'your-password',
host: 'localhost',
database: 'supamoto_db',
port: 5432,
ssl: false,
});
// Use the client
const customer = await db.customers.v1.selectCustomer({
customerId: 'C123',
});
```
### Connection Pool Configuration
The SDK uses PostgreSQL connection pooling. You can configure the pool with these options:
```typescript
const db = createDatabaseClient({
// Connection parameters
user: 'username',
password: 'password',
host: 'localhost',
database: 'supamoto_db',
port: 5432,
connectionString: 'postgresql://user:password@localhost:5432/db', // Alternative to individual params
// Pool configuration
max: 20, // maximum number of clients in the pool
min: 5, // minimum number of clients in the pool
idleTimeoutMillis: 30000, // how long a client is allowed to remain idle
connectionTimeoutMillis: 2000, // timeout when connecting a new client
// SSL configuration
ssl: {
rejectUnauthorized: false,
},
});
```
### Transactions
The SDK supports database transactions:
```typescript
await db.transaction(async (client) => {
// All operations within this block use the same transaction
const customer = await db.customers.v1.insertCustomer(
{
customerId: 'C123',
status: 'active',
},
client,
);
const phone = await db.phones.v1.insertPhone(
{
id: 'phone-123',
phoneNumber: Buffer.from('+1234567890'),
},
client,
);
await db.customerPhones.v1.insertCustomerPhone(
{
customerId: customer.customer_id,
phoneId: phone.id,
isPrimary: true,
},
client,
);
});
```
## Database Operations
### Customers
Manage customer data with encrypted personal information:
```typescript
// Select customers
const customer = await db.customers.v1.selectCustomer({
customerId: 'C123',
});
const customers = await db.customers.v1.selectCustomers({
customerIds: ['C123', 'customer-456'],
});
// Insert customer
const newCustomer = await db.customers.v1.insertCustomer({
customerId: 'C123',
fullName: Buffer.from('John Doe'),
email: Buffer.from('john@example.com'),
encryptedPin: Buffer.from('encrypted-pin'),
nationalId: Buffer.from('123456789'),
preferredLanguage: 'en',
address: Buffer.from('123 Main St'),
nameIndex: [Buffer.from('john'), Buffer.from('doe')],
addressIndex: [Buffer.from('123'), Buffer.from('main')],
countryIndex: 'US',
givenName: Buffer.from('John'),
familyName: Buffer.from('Doe'),
profileImage: Buffer.from('image-data'),
status: 'active',
errorMessage: undefined,
});
// Update customer
const updatedCustomer = await db.customers.v1.updateCustomer({
customerId: 'C123',
status: 'inactive',
errorMessage: 'Account suspended',
});
// Delete customer
const deletedCustomer = await db.customers.v1.deleteCustomer({
customerId: 'C123',
});
```
### Phones
Manage phone number data:
```typescript
// Select phones
const phone = await db.phones.v1.selectPhone({ id: 'phone-123' });
const phones = await db.phones.v1.selectPhones({ ids: ['phone-123', 'phone-456'] });
// Insert phone
const newPhone = await db.phones.v1.insertPhone({
id: 'phone-123',
phoneNumber: Buffer.from('+1234567890'),
firstSeen: '2024-01-01T00:00:00Z',
lastSeen: '2024-01-15T12:00:00Z',
numberOfVisits: 5,
});
// Update phone
const updatedPhone = await db.phones.v1.updatePhoneLastSeen({
id: 'phone-123',
lastSeen: '2024-01-20T15:30:00Z',
});
const updatedVisits = await db.phones.v1.updatePhoneNumberOfVisits({
id: 'phone-123',
numberOfVisits: 10,
});
// General update
const updated = await db.phones.v1.updatePhone({
id: 'phone-123',
lastSeen: '2024-01-20T15:30:00Z',
numberOfVisits: 10,
});
// Delete phone
const deletedPhone = await db.phones.v1.deletePhone({ id: 'phone-123' });
```
### Customer Phones
Link customers to their phone numbers:
```typescript
// Select customer phones
const customerPhone = await db.customerPhones.v1.selectCustomerPhone({
id: 'cp-123',
});
const customerPhones = await db.customerPhones.v1.selectCustomerPhones({
ids: ['cp-123', 'cp-456'],
});
const phonesByCustomer = await db.customerPhones.v1.selectCustomerPhonesByCustomerId({
customerId: 'C123',
});
const customersByPhone = await db.customerPhones.v1.selectCustomerPhonesByPhoneId({
phoneId: 'phone-123',
});
// Insert customer phone
const newCustomerPhone = await db.customerPhones.v1.insertCustomerPhone({
customerId: 'C123',
phoneId: 'phone-123',
isPrimary: true,
});
// Update primary status
const updatedPrimary = await db.customerPhones.v1.updateCustomerPhoneIsPrimary({
id: 'cp-123',
isPrimary: false,
});
// Delete customer phone
const deleted = await db.customerPhones.v1.deleteCustomerPhone({ id: 'cp-123' });
```
### Claims
Manage claim data and status:
```typescript
// Select claims
const claim = await db.claims.v1.selectClaim({ claimId: 'claim-123' });
const claims = await db.claims.v1.selectClaims({ claimIds: ['claim-123', 'claim-456'] });
const claimsByCustomer = await db.claims.v1.selectClaimsByCustomerId({
customerId: 'C123',
});
const claimsByCollection = await db.claims.v1.selectClaimsByCollectionId({
collectionId: 'collection-123',
});
const claimsByStatus = await db.claims.v1.selectClaimsByStatus({ status: 'pending' });
const claimsByCustomerAndCollection = await db.claims.v1.selectClaimsByCustomerIdAndCollectionId({
customerId: 'C123',
collectionId: 'collection-123',
});
// Insert claim
const newClaim = await db.claims.v1.insertClaim({
claimId: 'claim-123',
customerId: 'C123',
collectionId: 'collection-123',
status: 'pending',
});
// Upsert claim
const upsertedClaim = await db.claims.v1.upsertClaim({
claimId: 'claim-123',
customerId: 'C123',
collectionId: 'collection-123',
status: 'approved',
});
// Update claim
const updatedStatus = await db.claims.v1.updateClaimStatus({
claimId: 'claim-123',
status: 'approved',
});
const updatedCustomer = await db.claims.v1.updateClaimCustomerId({
claimId: 'claim-123',
customerId: 'customer-456',
});
// Delete claim
const deletedClaim = await db.claims.v1.deleteClaim({ claimId: 'claim-123' });
```
### Customer Credentials
Manage customer credential data:
```typescript
// Select credentials
const credential = await db.customerCredentials.v1.selectCustomerCredential({ id: 1 });
const credentials = await db.customerCredentials.v1.selectCustomerCredentials({ ids: [1, 2] });
const credentialsByCustomer = await db.customerCredentials.v1.selectCustomerCredentialsByCustomerId({
customerId: 'C123',
});
const credentialsByStatus = await db.customerCredentials.v1.selectCustomerCredentialsByStatus({
status: 'issued',
});
// Insert credential
const newCredential = await db.customerCredentials.v1.insertCustomerCredential({
customerId: 'C123',
status: 'pending',
});
// Update credential
const updatedCredential = await db.customerCredentials.v1.updateCustomerCredential({
id: 1,
status: 'issued',
});
// Delete credential
const deletedCredential = await db.customerCredentials.v1.deleteCustomerCredential({ id: 1 });
```
### Customer Onboardings
Track customer onboarding progress:
```typescript
// Select onboardings
const onboarding = await db.customerOnboardings.v1.selectCustomerOnboarding({
customerId: 'C123',
});
const onboardings = await db.customerOnboardings.v1.selectCustomerOnboardings({
customerIds: ['C123', 'customer-456'],
});
const onboardingsByStatus = await db.customerOnboardings.v1.selectCustomerOnboardingsByStatus({
status: 'lead',
});
// Insert onboarding
const newOnboarding = await db.customerOnboardings.v1.insertCustomerOnboarding({
customerId: 'C123',
status: 'lead',
});
// Update onboarding
const updatedOnboarding = await db.customerOnboardings.v1.updateCustomerOnboarding({
id: 1,
status: 'complete',
});
// Delete onboarding
const deletedOnboarding = await db.customerOnboardings.v1.deleteCustomerOnboarding({ id: 1 });
```
### Household Entities
Manage household entity data:
```typescript
// Select household entities
const entity = await db.householdEntities.v1.selectHouseholdEntity({
did: 'did:ixo:entity:123',
});
const entities = await db.householdEntities.v1.selectHouseholdEntities({
dids: ['did:ixo:entity:123', 'did:ixo:entity:456'],
});
const entitiesByIxoAccount = await db.householdEntities.v1.selectHouseholdEntitiesByIxoAccount({
ixoAccount: 'ixo1abc123',
});
// Insert entity
const newEntity = await db.householdEntities.v1.insertHouseholdEntity({
did: 'did:ixo:entity:123',
ixoAccount: 'ixo1abc123',
matrixRoomId: '!room123:matrix.org',
});
// Update entity
const updatedEntity = await db.householdEntities.v1.updateHouseholdEntity({
did: 'did:ixo:entity:123',
ixoAccount: 'ixo1abc123',
matrixRoomId: '!room456:matrix.org',
});
// Delete entity
const deletedEntity = await db.householdEntities.v1.deleteHouseholdEntity({
did: 'did:ixo:entity:123',
});
```
### Household Credentials
Manage household credential data:
```typescript
// Select credentials
const credential = await db.householdCredentials.v1.selectHouseholdCredential({ id: 1 });
const credentials = await db.householdCredentials.v1.selectHouseholdCredentials({ ids: [1, 2] });
const credentialsByEntity = await db.householdCredentials.v1.selectHouseholdCredentialsByHouseholdEntityDid({
householdEntityDid: 'did:ixo:entity:123',
});
// Insert credential
const newCredential = await db.householdCredentials.v1.insertHouseholdCredential({
householdEntityDid: 'did:ixo:entity:123',
status: 'pending',
});
// Update credential
const updatedCredential = await db.householdCredentials.v1.updateHouseholdCredential({
id: 1,
status: 'issued',
});
// Delete credential
const deletedCredential = await db.householdCredentials.v1.deleteHouseholdCredential({ id: 1 });
```
### IXO Accounts
Manage IXO blockchain accounts:
```typescript
// Select accounts
const account = await db.ixoAccounts.v1.selectIxoAccount({
address: 'ixo1abc123',
});
const accounts = await db.ixoAccounts.v1.selectIxoAccounts({
addresses: ['ixo1abc123', 'ixo1def456'],
});
const accountsByCustomer = await db.ixoAccounts.v1.selectIxoAccountsByCustomerId({
customerId: 'C123',
});
const accountsByDid = await db.ixoAccounts.v1.selectIxoAccountsByDid({
did: 'did:ixo:123',
});
// Insert account
const newAccount = await db.ixoAccounts.v1.insertIxoAccount({
address: 'ixo1abc123',
did: 'did:ixo:123',
customerId: 'C123',
encryptedMnemonic: 'encrypted-mnemonic',
isPrimary: true,
});
// Update account
const updatedAccount = await db.ixoAccounts.v1.updateIxoAccount({
address: 'ixo1abc123',
did: 'did:ixo:123',
customerId: 'C123',
encryptedMnemonic: 'new-encrypted-mnemonic',
isPrimary: false,
});
// Delete account
const deletedAccount = await db.ixoAccounts.v1.deleteIxoAccount({
address: 'ixo1abc123',
});
```
### Matrix Accounts
Manage Matrix account data:
```typescript
// Select accounts
const account = await db.matrixAccounts.v1.selectMatrixAccount({
address: 'matrix-address-123',
});
const accounts = await db.matrixAccounts.v1.selectMatrixAccounts({
addresses: ['matrix-address-123', 'matrix-address-456'],
});
const accountsByUsername = await db.matrixAccounts.v1.selectMatrixAccountsByUsername({
username: 'user123',
});
// Insert account
const newAccount = await db.matrixAccounts.v1.insertMatrixAccount({
address: 'matrix-address-123',
username: 'user123',
encryptedPassword: 'encrypted-password',
tempEncryptedMnemonic: 'temp-encrypted-mnemonic',
encryptedPin: 'encrypted-pin',
encryptedAccessToken: 'encrypted-access-token',
roomId: '!room123:matrix.org',
});
// Update account
const updatedAccount = await db.matrixAccounts.v1.updateMatrixAccount({
address: 'matrix-address-123',
tempEncryptedMnemonic: 'new-temp-encrypted-mnemonic',
encryptedPin: 'new-encrypted-pin',
encryptedAccessToken: 'new-encrypted-access-token',
roomId: '!room456:matrix.org',
});
// Delete account
const deletedAccount = await db.matrixAccounts.v1.deleteMatrixAccount({
address: 'matrix-address-123',
});
```
### Config
Manage configuration data:
```typescript
// Select config
const config = await db.config.v1.selectConfig({ id: 1 });
const configs = await db.config.v1.selectConfigs({ ids: [1, 2] });
const configByKey = await db.config.v1.selectConfigByKey({ key: 'app_name' });
const configsByKey = await db.config.v1.selectConfigsByKey({
key: 'feature_flag',
active: true,
});
// Insert config
const newConfig = await db.config.v1.insertConfig({
key: 'app_name',
value: 'Supamoto Bot',
active: true,
});
```
### Claim Issues
Manage claim issue data:
```typescript
// Select claim issues
const claimIssue = await db.claimIssues.v1.selectClaimIssue({ id: 1 });
const claimIssues = await db.claimIssues.v1.selectClaimIssues({ ids: [1, 2] });
const issuesByClaim = await db.claimIssues.v1.selectClaimIssuesByClaimId({
claimId: 'claim-123',
});
const issuesByCustomer = await db.claimIssues.v1.selectClaimIssuesByCustomerId({
customerId: 'C123',
});
const issuesByCollection = await db.claimIssues.v1.selectClaimIssuesByCollectionId({
collectionId: 'collection-123',
});
// Insert claim issue
const newClaimIssue = await db.claimIssues.v1.insertClaimIssue({
claimId: 'claim-123',
customerId: 'C123',
collectionId: 'collection-123',
reason: 'Invalid data provided',
});
// Update claim issue
const updatedClaimIssue = await db.claimIssues.v1.updateClaimIssue({
id: 1,
reason: 'Updated reason',
});
// Delete claim issue
const deletedClaimIssue = await db.claimIssues.v1.deleteClaimIssue({ id: 1 });
```
## Utilities
### Validators
Validate various data formats:
```typescript
import { utils } from '@ixo/supamoto-bot-sdk';
// Matrix validators
const isValidUserId = utils.validators.isValidUserId('@user:matrix.org');
const isValidRoomId = utils.validators.isValidRoomId('!room123:matrix.org');
const isValidRoomAlias = utils.validators.isValidRoomAlias('#room:matrix.org');
const isValidMxcLink = utils.validators.isValidMxcLink('mxc://matrix.org/abc123');
const isValidEventId = utils.validators.isValidEventId('$event123');
const isValidEventType = utils.validators.isValidEventType('m.room.message');
// IXO validators
const isValidDid = utils.validators.isValidDid('did:ixo:123');
const isValidAddress = utils.validators.isValidAddress('ixo1abc123');
const isValidCollectionId = utils.validators.isValidCollectionId('123');
// Bid validators
const isValidBid = utils.validators.isValidBid('{"data": "bid"}');
const isValidBidRole = utils.validators.isValidBidRole('SA'); // PO, EA, SA, IA
```
### Encryption
Handle encryption operations:
```typescript
import { utils } from '@ixo/supamoto-bot-sdk';
// Encryption utilities
const encrypted = utils.encryption.encrypt('sensitive data', 'password');
const decrypted = utils.encryption.decrypt(encrypted, 'password');
```
### Indexing
Handle search indexing:
```typescript
import { utils } from '@ixo/supamoto-bot-sdk';
// Indexing utilities
const nameIndex = utils.indexing.createNameIndex('John Doe');
const addressIndex = utils.indexing.createAddressIndex('123 Main St');
```
### Claims Utilities
Handle claim-related operations:
```typescript
import { utils } from '@ixo/supamoto-bot-sdk';
// Claims utilities
const processedClaim = utils.claims.processClaim(claimData);
const validatedClaim = utils.claims.validateClaim(claimData);
```
### Customers Utilities
Handle customer-related operations:
```typescript
import { utils } from '@ixo/supamoto-bot-sdk';
// Customer utilities
const processedCustomer = utils.customers.processCustomer(customerData);
const validatedCustomer = utils.customers.validateCustomer(customerData);
```
## Type Definitions
The SDK provides comprehensive TypeScript types for all database entities:
```typescript
import type {
// Core types
PoolConfig,
// Entity types
ICustomer,
ICustomers,
IPhone,
IPhones,
ICustomerPhone,
ICustomerPhones,
IClaim,
IClaims,
ICustomerCredential,
ICustomerCredentials,
ICustomerOnboarding,
ICustomerOnboardings,
IHouseholdEntity,
IHouseholdEntities,
IHouseholdCredential,
IHouseholdCredentials,
IIxoAccount,
IIxoAccounts,
IMatrixAccount,
IMatrixAccounts,
IConfig,
IConfigs,
IClaimIssue,
IClaimIssues,
} from '@ixo/supamoto-bot-sdk';
```
## Error Handling
The SDK throws exceptions for database errors. Always wrap database operations in try-catch blocks:
```typescript
try {
const customer = await db.customers.v1.selectCustomer({
customerId: 'C123',
});
console.log(customer);
} catch (error) {
console.error('Database error:', error);
// Handle the error appropriately
}
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.
## Support
For support, please open an issue on GitHub or contact the IXO team.
---
**Note**: This SDK is designed for use with the Supamoto Bot ecosystem and requires a PostgreSQL database with the appropriate schema.
```
```