docs: Add Swift SDK README with comprehensive API documentation and implement authentication provider with JWT support

- Add README.md with installation instructions, architecture overview, and API examples for all SDK modules
- Add AuthProvider class with API key and JWT token support (generateJWTToken, validateJWTToken, getHeaders, clearTokenCache methods)
- Add HTTPClient base class with retry logic, error handling, and timeout management
- Add GraphQLAPI, PaymentAPI, RatingPlanAPI, SubscriberAPI, SystemAPI, and UsageAPI modules
- Add TelecomSDK main client integrating all API
This commit is contained in:
nutcas3
2026-04-25 04:53:22 +03:00
parent 511f7be357
commit f6590462f5
10 changed files with 796 additions and 244 deletions
+39 -244
View File
@@ -10,8 +10,16 @@ public class TelecomSDK {
// MARK: - Properties
private let config: TelecomConfig
private let authProvider: AuthProvider
private let httpClient: HTTPClient
private let webSocketClient: WebSocketClient
// API modules
public let subscribers: SubscriberAPI
public let usage: UsageAPI
public let payments: PaymentAPI
public let ratingPlans: RatingPlanAPI
public let system: SystemAPI
public let graphql: GraphQLAPI
// MARK: - Initialization
@@ -19,256 +27,35 @@ public class TelecomSDK {
/// - Parameter config: Configuration for the SDK
public init(config: TelecomConfig = TelecomConfig()) {
self.config = config
self.httpClient = HTTPClient(config: config)
self.webSocketClient = WebSocketClient(config: config)
}
// MARK: - Subscriber Management
/// Get subscriber by ID
/// - Parameter id: Subscriber ID
/// - Returns: Subscriber information
public func getSubscriber(id: Int64) async throws -> Subscriber {
return try await httpClient.get(path: "/v1/subscribers/\(id)")
}
/// List subscribers with pagination
/// - Parameters:
/// - page: Page number
/// - pageSize: Page size
/// - status: Optional status filter
/// - Returns: Paginated list of subscribers
public func listSubscribers(
page: Int = 1,
pageSize: Int = 50,
status: SubscriberStatus? = nil
) async throws -> SubscriberList {
var queryParams: [String: String] = [
"page": "\(page)",
"page_size": "\(pageSize)"
]
self.authProvider = AuthProvider(apiKey: config.apiKey, jwtSecret: config.jwtSecret)
self.httpClient = HTTPClient(config: config, authProvider: authProvider)
if let status = status {
queryParams["status"] = status.rawValue
}
return try await httpClient.get(path: "/v1/subscribers", queryParams: queryParams)
// Initialize API modules
self.subscribers = SubscriberAPI(client: httpClient)
self.usage = UsageAPI(client: httpClient)
self.payments = PaymentAPI(client: httpClient)
self.ratingPlans = RatingPlanAPI(client: httpClient)
self.system = SystemAPI(client: httpClient)
self.graphql = GraphQLAPI(client: httpClient)
}
/// Create a new subscriber
/// - Parameter request: Create subscriber request
/// - Returns: Created subscriber
public func createSubscriber(request: CreateSubscriberRequest) async throws -> Subscriber {
return try await httpClient.post(path: "/v1/subscribers", body: request)
// MARK: - Authentication Methods
/// Generate a JWT token for authentication
public func generateJWTToken(userID: String, expiryHours: Int, additionalClaims: [String: Any] = [:]) throws -> String {
return try authProvider.generateJWTToken(userID: userID, expiryHours: expiryHours, additionalClaims: additionalClaims)
}
/// Update an existing subscriber
/// - Parameters:
/// - id: Subscriber ID
/// - request: Update subscriber request
/// - Returns: Updated subscriber
public func updateSubscriber(id: Int64, request: UpdateSubscriberRequest) async throws -> Subscriber {
return try await httpClient.put(path: "/v1/subscribers/\(id)", body: request)
/// Validate a JWT token
public func validateJWTToken(_ token: String) throws -> [String: Any] {
return try authProvider.validateJWTToken(token)
}
/// Suspend a subscriber
/// - Parameter id: Subscriber ID
/// - Returns: Suspended subscriber
public func suspendSubscriber(id: Int64) async throws -> Subscriber {
return try await httpClient.post(path: "/v1/subscribers/\(id)/suspend")
}
// MARK: - Cleanup
/// Activate a suspended subscriber
/// - Parameter id: Subscriber ID
/// - Returns: Activated subscriber
public func activateSubscriber(id: Int64) async throws -> Subscriber {
return try await httpClient.post(path: "/v1/subscribers/\(id)/activate")
}
/// Terminate a subscriber
/// - Parameter id: Subscriber ID
/// - Returns: Success status
public func terminateSubscriber(id: Int64) async throws -> Bool {
return try await httpClient.delete(path: "/v1/subscribers/\(id)")
}
// MARK: - Usage Management
/// Get usage statistics for a subscriber
/// - Parameters:
/// - subscriberId: Subscriber ID
/// - startDate: Start date
/// - endDate: End date
/// - Returns: Usage statistics
public func getUsageStats(
subscriberId: Int64,
startDate: Date,
endDate: Date
) async throws -> UsageStats {
let formatter = ISO8601DateFormatter()
formatter.timeZone = TimeZone.current
let queryParams: [String: String] = [
"start_date": formatter.string(from: startDate),
"end_date": formatter.string(from: endDate)
]
return try await httpClient.get(
path: "/v1/subscribers/\(subscriberId)/usage",
queryParams: queryParams
)
}
/// List usage events with filtering
/// - Parameters:
/// - subscriberId: Optional subscriber ID filter
/// - usageType: Optional usage type filter
/// - startDate: Optional start date filter
/// - endDate: Optional end date filter
/// - page: Page number
/// - pageSize: Page size
/// - Returns: Paginated list of usage events
public func listUsageEvents(
subscriberId: Int64? = nil,
usageType: UsageType? = nil,
startDate: Date? = nil,
endDate: Date? = nil,
page: Int = 1,
pageSize: Int = 50
) async throws -> UsageEventList {
var queryParams: [String: String] = [
"page": "\(page)",
"page_size": "\(pageSize)"
]
if let subscriberId = subscriberId {
queryParams["subscriber_id"] = "\(subscriberId)"
}
if let usageType = usageType {
queryParams["usage_type"] = usageType.rawValue
}
if let startDate = startDate {
let formatter = ISO8601DateFormatter()
formatter.timeZone = TimeZone.current
queryParams["start_date"] = formatter.string(from: startDate)
}
if let endDate = endDate {
let formatter = ISO8601DateFormatter()
formatter.timeZone = TimeZone.current
queryParams["end_date"] = formatter.string(from: endDate)
}
return try await httpClient.get(path: "/v1/usage/events", queryParams: queryParams)
}
/// Get real-time usage for a subscriber
/// - Parameter subscriberId: Subscriber ID
/// - Returns: Real-time usage data
public func getRealTimeUsage(subscriberId: Int64) async throws -> RealTimeUsage {
return try await httpClient.get(path: "/v1/subscribers/\(subscriberId)/realtime")
}
// MARK: - Payment Management
/// Create a payment transaction
/// - Parameter request: Create payment request
/// - Returns: Created payment transaction
public func createPaymentTransaction(request: CreatePaymentRequest) async throws -> PaymentTransaction {
return try await httpClient.post(path: "/v1/payments/transactions", body: request)
}
/// Get payment transaction by ID
/// - Parameter transactionId: Transaction ID
/// - Returns: Payment transaction
public func getPaymentTransaction(transactionId: String) async throws -> PaymentTransaction {
return try await httpClient.get(path: "/v1/payments/transactions/\(transactionId)")
}
/// List payment transactions with filtering
/// - Parameters:
/// - subscriberId: Optional subscriber ID filter
/// - status: Optional status filter
/// - page: Page number
/// - pageSize: Page size
/// - Returns: Paginated list of payment transactions
public func listPaymentTransactions(
subscriberId: Int64? = nil,
status: PaymentStatus? = nil,
page: Int = 1,
pageSize: Int = 50
) async throws -> PaymentTransactionList {
var queryParams: [String: String] = [
"page": "\(page)",
"page_size": "\(pageSize)"
]
if let subscriberId = subscriberId {
queryParams["subscriber_id"] = "\(subscriberId)"
}
if let status = status {
queryParams["status"] = status.rawValue
}
return try await httpClient.get(path: "/v1/payments/transactions", queryParams: queryParams)
}
// MARK: - Rating Plans
/// List all available rating plans
/// - Returns: List of rating plans
public func listRatingPlans() async throws -> [RatingPlan] {
return try await httpClient.get(path: "/v1/rating-plans")
}
/// Get rating plan by ID
/// - Parameter planId: Plan ID
/// - Returns: Rating plan
public func getRatingPlan(planId: String) async throws -> RatingPlan {
return try await httpClient.get(path: "/v1/rating-plans/\(planId)")
}
// MARK: - System Management
/// Get system statistics
/// - Returns: System statistics
public func getSystemStats() async throws -> SystemStats {
return try await httpClient.get(path: "/v1/system/stats")
}
/// Get system health status
/// - Returns: Health status
public func getHealthStatus() async throws -> HealthStatus {
return try await httpClient.get(path: "/v1/health")
}
// MARK: - WebSocket Support
/// Connect to WebSocket for real-time updates
/// - Parameter messageHandler: Closure to handle WebSocket messages
/// - Returns: Async stream of WebSocket messages
public func connectWebSocket(
messageHandler: @escaping (WebSocketMessage) async -> Void
) -> AsyncThrowingStream<WebSocketMessage, Error> {
return try await webSocketClient.connect(messageHandler: messageHandler)
}
// MARK: - GraphQL Support
/// Execute a GraphQL query
/// - Parameters:
/// - query: GraphQL query string
/// - variables: Optional query variables
/// - Returns: GraphQL response
public func executeGraphQLQuery(
query: String,
variables: [String: Any]? = nil
) async throws -> GraphQLResponse {
let request = GraphQLRequest(query: query, variables: variables ?? [:])
return try await httpClient.post(path: "/graphql", body: request)
/// Close the SDK and cleanup resources
public func close() {
httpClient.close()
}
}
@@ -280,20 +67,28 @@ public struct TelecomConfig {
public var apiURL: String
/// API key for authentication
public var apiKey: String?
/// JWT secret for token generation
public var jwtSecret: String?
/// Request timeout in seconds
public var timeout: TimeInterval
/// Maximum number of retry attempts
public var maxRetries: Int
/// Delay between retries in seconds
public var retryDelay: TimeInterval
public init(
apiURL: String = "http://localhost:8000",
apiKey: String? = nil,
jwtSecret: String? = nil,
timeout: TimeInterval = 30.0,
maxRetries: Int = 3
maxRetries: Int = 3,
retryDelay: TimeInterval = 1.0
) {
self.apiURL = apiURL
self.apiKey = apiKey
self.jwtSecret = jwtSecret
self.timeout = timeout
self.maxRetries = maxRetries
self.retryDelay = retryDelay
}
}