core

This module provides core functionality, data models, types, and utilities used across all Smart1 SDK modules.

Overview

The core module contains:

Common data models used throughout the SDK
Result types for operation outcomes
Error handling structures
Common types and enums
Constants
Conversion utilities

Main Components

ResultS1SDK

Generic result type for SDK operations.

Sealed Class:

Success<T>(data: T) - Successful operation with data
Error<E>(error: E) - Failed operation with error

ErrorS1SDK

Interface for SDK error types. Implementations include:

Error Types:

ApiError - API-related errors
CommonError - Common validation and logic errors
SdkInitConfigError - SDK initialization errors
ApiListError - API list operation errors
RegisterUserOperatorError - API Errors when creating a new User Operator

Models

SessionData

Contains user session information.

Properties:

email: String - User's email
phoneNumber: String - User's phone number
userId: Long - User identifier
roleId: Long - Role identifier
permission: List<String> - List of permissions
clientName: String - Client name
roleName: String - Role name
companyIds: List<Long> - Associated company IDs
accessToken: String - Access token
expireTokenUTC: String - Token expiration (UTC)
tokenType: String - Token type
addedOn: String - Account creation date
key: String - Key
accessTokenFirebase: String - Firebase access token
accessTokenPubSub: String - PubSub access token
projectId: String - Project ID for PubSub
topicName: String - Topic name for PubSub

CoordinatesData

Geographic coordinates representation.

Properties:

latitude: Double - Latitude (-90 to 90)
longitude: Double - Longitude (-180 to 180)

DataSet

Paginated data container.

Properties:

data: List<T> - List of items
paginationInfo: PaginationInfo - Pagination metadata

PaginationInfo

Pagination metadata.

Properties:

currentPage: Int - Current page number
totalPages: Int - Total number of pages
totalRecords: Int - Total number of records
pageSize: Int - Items per page

CapacityInfo

Capacity information for orders, routes, etc.

Properties:

name: String - Capacity type name
value: Double - Capacity value
unit: String - Unit of measurement

Types

ApiLogicalOperator

Logical operators for API queries.

Values:

AND - Logical AND operation
OR - Logical OR operation

ApiSearchType

Search types for API queries.

Values:

EXACT - Exact match search
CONTAINS - Partial match search

ApiSortType

Sort order types.

Values:

ASC - Ascending order
DESC - Descending order

FleetType

Fleet type classifications.

Values:

OWN - Own fleet
THIRD - Third party fleet
MIXED - Mixed fleet
UNKNOWN - Unknown fleet type

LoadType

Load type classifications.

Values:

REAR - Rear load
SIDE - Side load
MIXED - Mixed load
UNKNOWN - Unknown load type

PlaceStatusType

Place status types.

Values:

ACTIVE - Active place
INACTIVE - Inactive place
DELETED - Deleted place
UNKNOWN - Unknown status

Constants

Common constants used across the SDK.

Values:

DEFAULT_RECORD_QUANTITY_PER_PAGE: Int - Default pagination size (100)
EMPTY_STR: String - Empty string constant ("")
INT_INVALID: Int - Invalid integer marker (-1)
LONG_INVALID: Long - Invalid long marker (-1L)
DOUBLE_INVALID: Double - Invalid double marker (-1.0)

Usage Examples

Working with ResultS1SDK

import com.servinformacion.smart1sdk.android.core.ResultS1SDK
import com.servinformacion.smart1sdk.android.core.error.ErrorS1SDK

suspend fun fetchData(): ResultS1SDK<String, ErrorS1SDK> {
    return try {
        val data = performOperation()
        ResultS1SDK.Success(data)
    } catch (e: Exception) {
        ResultS1SDK.Error(ErrorS1SDK.UnknownError(e.message))
    }
}

fun handleResult(result: ResultS1SDK<String, ErrorS1SDK>) {
    when (result) {
        is ResultS1SDK.Success -> {
            println("Success: ${result.data}")
        }
        is ResultS1SDK.Error -> {
            when (val error = result.error) {
                is ApiError -> println("API Error")
                is CommonError -> println("Common Error")
                is DbError -> println("Database Error")
                is SdkInitConfigError -> println("SDK Init Error")
                is ApiListError -> println("API List Error")
                else -> println("Unknown Error")
            }
        }
    }
}

Using CoordinatesData

import com.servinformacion.smart1sdk.android.core.model.CoordinatesData

fun createLocation(lat: Double, lon: Double): CoordinatesData {
    return CoordinatesData(
        latitude = lat,
        longitude = lon
    )
}

fun validateCoordinates(coords: CoordinatesData): Boolean {
    return coords.latitude in -90.0..90.0 &&
           coords.longitude in -180.0..180.0
}

// Example usage
val location = createLocation(40.7128, -74.0060) // New York
if (validateCoordinates(location)) {
    println("Valid coordinates: ${location.latitude}, ${location.longitude}")
}

Working with Paginated Data

import com.servinformacion.smart1sdk.android.core.model.DataSet
import com.servinformacion.smart1sdk.android.core.model.PaginationInfo

fun displayPaginatedData(dataSet: DataSet<String>) {
    println("Page ${dataSet.paginationInfo.currentPage} of ${dataSet.paginationInfo.totalPages}")
    println("Total records: ${dataSet.paginationInfo.totalRecords}")
    println("Items on this page: ${dataSet.data.size}")
    
    dataSet.data.forEachIndexed { index, item ->
        println("${index + 1}. $item")
    }
    
    val hasNextPage = dataSet.paginationInfo.currentPage < dataSet.paginationInfo.totalPages
    val hasPreviousPage = dataSet.paginationInfo.currentPage 1
    
    println("Has next page: $hasNextPage")
    println("Has previous page: $hasPreviousPage")
}

Using API Search Types

import com.servinformacion.smart1sdk.android.core.types.ApiSearchType
import com.servinformacion.smart1sdk.android.core.types.ApiLogicalOperator

fun buildSearchQuery(
    searchTerm: String,
    searchType: ApiSearchType,
    operator: ApiLogicalOperator
) {
    when (searchType) {
        ApiSearchType.EXACT -> println("Searching for exact match: $searchTerm")
        ApiSearchType.CONTAINS -> println("Searching for contains: $searchTerm")
        ApiSearchType.STARTS_WITH -> println("Searching for starts with: $searchTerm")
        ApiSearchType.ENDS_WITH -> println("Searching for ends with: $searchTerm")
    }
    
    when (operator) {
        ApiLogicalOperator.AND -> println("Using AND operator")
        ApiLogicalOperator.OR -> println("Using OR operator")
    }
}

Using Sort Types

import com.servinformacion.smart1sdk.android.core.types.ApiSortType

data class SortConfig(
    val field: String,
    val sortType: ApiSortType
)

fun applySorting(items: List<Int>, sortType: ApiSortType): List<Int> {
    return when (sortType) {
        ApiSortType.ASC -> items.sorted()
        ApiSortType.DESC -> items.sortedDescending()
    }
}

// Example usage
val numbers = listOf(5, 2, 8, 1, 9)
val ascending = applySorting(numbers, ApiSortType.ASC)
val descending = applySorting(numbers, ApiSortType.DESC)

println("Ascending: $ascending")   // [1, 2, 5, 8, 9]
println("Descending: $descending") // [9, 8, 5, 2, 1]

Working with Capacity Info

import com.servinformacion.smart1sdk.android.core.model.CapacityInfo

fun checkCapacity(
    current: CapacityInfo,
    limit: Double
): Boolean {
    return current.value limit
}

// Example usage
val weightCapacity = CapacityInfo(
    name = "Weight",
    value = 500.0,
    unit = "kg"
)

val isOverLimit = checkCapacity(
    current = weightCapacity,
    limit = 450.0
)

println("Capacity: ${weightCapacity.value} ${weightCapacity.unit}")
println("Over limit: $isOverLimit") // true

Using Constants

import com.servinformacion.smart1sdk.android.core.Constants

fun initializeDefaults() {
    val pageSize = Constants.DEFAULT_RECORD_QUANTITY_PER_PAGE
    val emptyString = Constants.EMPTY_STR
    val invalidId = Constants.INT_INVALID
    
    println("Default page size: $pageSize")
    println("Empty string: '$emptyString'")
    println("Invalid ID marker: $invalidId")
}

fun isValidId(id: Int): Boolean {
    return id != Constants.INT_INVALID && id 0
}

Error Handling Pattern

import com.servinformacion.smart1sdk.android.core.ResultS1SDK
import com.servinformacion.smart1sdk.android.core.error.ErrorS1SDK

class DataRepository {
    
    suspend fun fetchData(): ResultS1SDK<List<String>, ErrorS1SDK> {
        return try {
            // Simulate API call
            val data = performApiCall()
            ResultS1SDK.Success(data)
        } catch (e: Exception) {
            ResultS1SDK.Error(
                CommonError.UnknownError
            )
        }
    }
    
    private suspend fun performApiCall(): List<String> {
        // API call implementation
        return listOf("Item 1", "Item 2", "Item 3")
    }
}

class DataViewModel : ViewModel() {
    
    private val repository = DataRepository()
    
    fun loadData() {
        viewModelScope.launch {
            val result = repository.fetchData()
            
            when (result) {
                is ResultS1SDK.Success -> {
                    // Update UI with data
                    updateUI(result.data)
                }
                is ResultS1SDK.Error -> {
                    // Show error message
                    showError(result.error)
                }
            }
        }
    }
    
    private fun updateUI(data: List<String>) {
        println("Loaded ${data.size} items")
    }
    
    private fun showError(error: ErrorS1SDK) {
        println("Error: $error")
    }
}

Session Data Management

import com.servinformacion.smart1sdk.android.core.model.SessionData

class SessionManager {
    
    private var currentSession: SessionData? = null
    
    fun setSession(sessionData: SessionData) {
        currentSession = sessionData
        println("Session set for user: ${sessionData.email}")
        println("User ID: ${sessionData.userId}")
        println("Companies: ${sessionData.companyIds}")
        println("Role: ${sessionData.roleName}")
    }
    
    fun isSessionValid(): Boolean {
        val session = currentSession ?: return false
        // Check if session is expired
        // Implementation depends on date parsing
        return session.accessToken.isNotEmpty()
    }
    
    fun getUserId(): Long? {
        return currentSession?.userId
    }
    
    fun getCompanyIds(): List<Long> {
        return currentSession?.companyIds ?: emptyList()
    }
    
    fun clearSession() {
        currentSession = null
        println("Session cleared")
    }
}

Important Notes

Result Type: All SDK operations return ResultS1SDK for consistent error handling.
Error Hierarchy: Errors are categorized for easier handling and debugging.
Pagination: Use DataSet and PaginationInfo for paginated responses.
Coordinates: Latitude must be between -90 and 90, longitude between -180 and 180.
Constants: Use provided constants instead of hardcoding values.
Type Safety: All types are strongly typed for compile-time safety.
Immutability: Models are immutable data classes.

Best Practices

Error Handling: Always handle both success and error cases
Null Safety: Use nullable types appropriately
Constants: Use SDK constants for consistency
Type Usage: Use appropriate types for search, sort, and filter operations
Validation: Validate coordinates and other data before use
Pagination: Handle pagination properly in UI
Session Management: Keep session data secure and up to date

Use Cases

Result Handling: Consistent success/error handling across all operations
Pagination: Display large datasets with pagination
Location Services: Work with geographic coordinates
Search & Filter: Build complex search queries
Capacity Management: Track and validate capacities
Session Management: Handle user sessions
Error Reporting: Categorize and report errors

Packages

com.servinformacion.smart1sdk.android.core

androidJvm

com.servinformacion.smart1sdk.android.core.error

androidJvm

com.servinformacion.smart1sdk.android.core.model

androidJvm

com.servinformacion.smart1sdk.android.core.types

androidJvm