API 레퍼런스

public final class Deplite: @unchecked Sendable {
    public static let defaultBaseURL: URL    // https://api.deplite.io/v1
    public let apiToken: String
    public let baseURL: URL
    public let triggers: Triggers
    public let files: Files
 
    public init(
        apiToken: String,
        baseURL: URL = Deplite.defaultBaseURL,
        session: URLSession = .shared
    )
}

public static func enroll(
    installCode: String,
    name: String,
    hostname: String? = nil,
    os: String? = nil,
    agentVersion: String? = nil,
    baseURL: URL = Deplite.defaultBaseURL,
    session: URLSession = .shared
) async throws -> Enrollment

let enrollment = try await Deplite.enroll(
    installCode: installCode,
    name: "kiosk-seoul-01"
)
try secureStore.save(enrollment)   // identity + privateKey

public func run(
    triggerId: String,
    params: JSONValue? = nil,
    workflowName: String? = nil,
    ref: String? = nil,
    debug: Bool = false,
    idempotencyKey: String? = nil
) async throws -> TriggerRunResult

let job = try await deplite.triggers.run(
    triggerId: triggerId,
    params: ["ref": "main", "actor": "sehyun"],
    idempotencyKey: "release-\(UUID().uuidString)"
)
 
print(job.jobId, job.status)

public func upload(
    fileURL: URL,
    cleanupRule: CleanupRule = .ttl(seconds: 86_400),
    filename: String? = nil,
    contentType: String? = nil,
    bindingId: String? = nil
) async throws -> FileMeta

let uploaded = try await deplite.files.upload(
    fileURL: ipaURL,
    cleanupRule: .ttl(seconds: 3600),
    contentType: "application/octet-stream"
)
 
_ = try await deplite.triggers.run(
    triggerId: triggerId,
    params: ["ipaFileId": .string(uploaded.id), "ref": .string("main")]
)

public func presignUpload(
    cleanupRule: CleanupRule,
    filename: String? = nil,
    contentType: String? = nil,
    bindingId: String? = nil
) async throws -> PresignedUpload

public func completeUpload(fileId: String) async throws -> FileMeta
public func downloadURL(fileId: String) async throws -> URL
@discardableResult
public func download(fileId: String, to destination: URL) async throws -> URL
public func get(fileId: String) async throws -> FileMeta
public func list(bindingId: String? = nil, status: String? = nil) async throws -> [FileMeta]
public func delete(fileId: String) async throws

public final class DepliteAgent: @unchecked Sendable {
    public let identity: AgentIdentity
    public let workflows: AgentWorkflows
    public let jobs: AgentJobs
    public let files: AgentFiles
 
    public init(
        identity: AgentIdentity,
        privateKey: Data,            // 정확히 32바이트
        session: URLSession = .shared
    ) throws
}

public func heartbeat() async throws

public func updateIdentity(
    hostname: String? = nil,
    os: String? = nil,
    agentVersion: String? = nil
) async throws

public func events() -> AsyncThrowingStream<AgentEvent, Error>

for try await event in agent.events() {
    switch event {
    case .deploy(let payload, _):
        try await handleDeploy(payload)
    case .syncWorkflows:
        _ = try await agent.workflows.report(loadLocal())
    case .revoke:
        return
    case .ping:
        continue
    case .unknown(let name, _):
        print("unknown:", name)
    }
}

@discardableResult
public func appendLogs(jobId: String, items: [LogItem]) async throws -> Int

public func reportResult(jobId: String, result: JobResult) async throws

do {
    let output = try await runWorkflow(payload)
    try await agent.jobs.reportResult(
        jobId: payload.jobId,
        result: .success(output: output)
    )
} catch {
    try await agent.jobs.reportResult(
        jobId: payload.jobId,
        result: .failed(exitCode: 1, errorMessage: "\(error)")
    )
}

public func upload(jobId: String, fileURL: URL, ...) async throws -> FileMeta
public func presignUpload(jobId: String, ...) async throws -> PresignedUpload
public func complete(fileId: String) async throws -> FileMeta
public func downloadURL(fileId: String) async throws -> URL
public func download(fileId: String, to: URL) async throws -> URL
public func get(fileId: String) async throws -> FileMeta
public func delete(fileId: String) async throws

@discardableResult
public func report(_ workflows: [WorkflowReport]) async throws -> Int

public struct Enrollment: Sendable, Equatable {
    public let identity: AgentIdentity
    public let privateKey: Data       // raw 32-byte 개인키
}

public struct AgentIdentity: Codable, Sendable, Equatable {
    public let agentId: String
    public let organizationId: String
    public let baseURL: URL
    public let serverPublicKeyPEM: String
}

public enum AgentEvent: Sendable {
    case deploy(payload: DeployPayload, signature: String)
    case revoke
    case syncWorkflows
    case ping
    case unknown(name: String, data: String)
}

public struct DeployPayload: Sendable, Equatable, Decodable {
    public let jobId: String
    public let workflowName: String
    public let debug: Bool
    public let ref: String?
    public let params: JSONValue?
    public let issuedAt: Int64
    public let nonce: String
    public let force: Bool
    public let forceReason: String?
}

public struct TriggerRunResult: Decodable, Sendable, Equatable {
    public let jobId: String
    public let status: String
    public let idempotent: Bool
    public let timedOut: Bool
    public let exitCode: Int?
    public let errorMessage: String?
    public let output: JSONValue?
    public let statusUrl: URL?
}

public enum CleanupRule: Sendable, Equatable {
    case ttl(seconds: Int64)           // 60s ≤ seconds ≤ 90일
    case persistent
    case onJobEnd                      // Agent Files 전용
}

public struct FileMeta: Decodable, Sendable, Equatable {
    public let id: String
    public let bindingId: String?
    public let jobId: String?
    public let filename: String?
    public let contentType: String?
    public let size: Int64?
    public let status: String?
    public let cleanupRule: String?
    public let expiresAt: String?
    public let createdAt: String?
}

public struct PresignedUpload: Decodable, Sendable, Equatable {
    public let fileId: String
    public let uploadUrl: URL
    public let uploadHeaders: [String: String]?
    public let expiresInSeconds: Int?
}

public enum LogStream: String, Codable, Sendable { case raw, system }
public enum LogLevel:  String, Codable, Sendable { case info, warn, error }
 
public struct LogItem: Sendable, Equatable {
    public let seq: Int
    public let stream: LogStream
    public let content: String
    public let stepName: String?
    public let level: LogLevel?
}

public enum JobStatus: String, Codable, Sendable {
    case running, success, failed, timeout, rejected
}
 
public struct JobResult: Sendable, Equatable {
    public let status: JobStatus
    public let exitCode: Int?
    public let errorMessage: String?
    public let output: JSONValue?
    public let rejection: Rejection?
 
    public struct Rejection: Sendable, Equatable {
        public let reason: String
        public let limitType: String?
        public let retryAfterSeconds: Int?
        public let bypassedLimits: [String]
    }
 
    public static func running() -> JobResult
    public static func success(exitCode: Int = 0, output: JSONValue? = nil) -> JobResult
    public static func failed(exitCode: Int? = nil, errorMessage: String? = nil) -> JobResult
    public static func timeout(errorMessage: String? = nil) -> JobResult
    public static func rejected(_ rejection: Rejection) -> JobResult
}

public struct WorkflowReport: Codable, Sendable, Equatable {
    public let name: String
    public let verboseSteps: [String]
    public let secretsKeys: [String]
}

public enum JSONValue: Codable, Sendable, Equatable {
    case null
    case bool(Bool)
    case int(Int64)
    case double(Double)
    case string(String)
    case array([JSONValue])
    case object([String: JSONValue])
}

public enum DepliteError: Error, Sendable {
    case api(statusCode: Int, body: String)
    case unauthorized(statusCode: Int, body: String)
    case transport(underlying: Error)
    case decoding(underlying: Error, body: String)
    case invalidPrivateKey
    case signing(reason: String)
    case sseClosed(reason: String)
}

do {
    _ = try await deplite.triggers.run(triggerId: triggerId)
} catch DepliteError.unauthorized {
    // 토큰 회수·교체 필요
} catch let DepliteError.api(status, _) where status == 429 || status >= 500 {
    // 백오프 후 재시도
} catch let DepliteError.api(_, _) {
    // 4xx 클라이언트 오류
} catch {
    // 네트워크·기타
}