API 레퍼런스

new Deplite(options: DepliteOptions)

static Deplite.enroll(options): Promise<Enrollment>

const enrollment = await Deplite.enroll({
  installCode: process.env.INSTALL_CODE!,
  name: 'kiosk-seoul-01',
})
 
// 반환값을 먼저 저장한 뒤 후속 로직 시작
await secureStore.save(enrollment)   // { identity, privateKey }

triggers.run(options): Promise<TriggerRunResult>

const job = await deplite.triggers.run({
  triggerId: process.env.TRIGGER_ID!,
  params: { ref: 'main', actor: 'sehyun' },
  idempotencyKey: `release-${Date.now()}`,
})
 
console.log(job.jobId, job.status)
// sync 트리거였다면 job.output 도 사용 가능

files.upload(options): Promise<FileMeta>

const uploaded = await deplite.files.upload({
  file: { path: './build/app.apk' },
  cleanupRule: { kind: 'ttl', ttlSeconds: 3600 },
  contentType: 'application/vnd.android.package-archive',
})
 
// uploaded.id 를 트리거 params 로 전달
await deplite.triggers.run({
  triggerId: TRIGGER_ID,
  params: { apkFileId: uploaded.id },
})

files.presignUpload(options): Promise<PresignedUpload>

files.completeUpload(options: { fileId: string }): Promise<FileMeta>

files.downloadUrl(options: { fileId: string }): Promise<string>

files.download(options: { fileId: string; to: string }): Promise<string>

files.get(options: { fileId: string }): Promise<FileMeta>
files.list(options?: { bindingId?: string; status?: string }): Promise<FileMeta[]>
files.delete(options: { fileId: string }): Promise<void>

new DepliteAgent(options: DepliteAgentOptions)

agent.heartbeat(): Promise<void>

agent.updateIdentity(patch: { hostname?; os?; agentVersion? }): Promise<void>

agent.events(options?: { signal?: AbortSignal }): AsyncIterable<AgentEvent>

for await (const ev of agent.events()) {
  switch (ev.type) {
    case 'deploy':
      await handleDeploy(ev.payload)
      break
    case 'sync_workflows':
      await reportWorkflows()
      break
    case 'revoke':
      return                         // 루프 종료
    case 'ping':
      break                          // keep-alive 무시
  }
}

jobs.appendLogs(options: { jobId: string; items: LogItem[] }): Promise<number>

jobs.reportResult(options: { jobId: string; result: JobResult }): Promise<void>

import { JobResult } from '@deplite/sdk'
 
try {
  const output = await runWorkflow(payload)
  await agent.jobs.reportResult({
    jobId: payload.jobId,
    result: JobResult.success({ exitCode: 0, output }),
  })
} catch (e) {
  await agent.jobs.reportResult({
    jobId: payload.jobId,
    result: JobResult.failed({ exitCode: 1, errorMessage: String(e) }),
  })
}

agentFiles.upload(options): Promise<FileMeta>
agentFiles.presignUpload(options): Promise<PresignedUpload>
agentFiles.complete(options: { fileId }): Promise<FileMeta>
agentFiles.downloadUrl(options: { fileId }): Promise<string>
agentFiles.download(options: { fileId, to }): Promise<string>
agentFiles.get(options: { fileId }): Promise<FileMeta>
agentFiles.delete(options: { fileId }): Promise<void>

workflows.report(workflows: WorkflowReport[]): Promise<number>

interface Enrollment {
  identity: AgentIdentity
  privateKey: Uint8Array     // raw 32-byte 개인키
}

interface AgentIdentity {
  agentId: string
  organizationId: string
  baseUrl: string
  serverPublicKeyPem: string  // deploy 이벤트 서명 검증용
}

type AgentEvent =
  | { type: 'deploy';          payload: DeployPayload; signature: string }
  | { type: 'revoke' }
  | { type: 'sync_workflows' }
  | { type: 'ping' }
  | { type: 'unknown';         name: string; data: string }

interface DeployPayload {
  jobId: string
  workflowName: string
  debug: boolean
  ref?: string
  params?: unknown
  issuedAt: number
  nonce: string
  force: boolean
  forceReason?: string
}

interface TriggerRunResult {
  jobId: string
  status: string             // 'running' | 'success' | 'failed' | 'timeout' | 'rejected'
  idempotent: boolean        // 동일 키 재사용 여부
  timedOut: boolean
  exitCode?: number
  errorMessage?: string
  output?: unknown
  statusUrl?: string
}

type CleanupRule =
  | { kind: 'ttl'; ttlSeconds: number }   // 60s ≤ ttl ≤ 90일
  | { kind: 'persistent' }
  | { kind: 'on_job_end' }                // Agent Files 전용

type UploadInput =
  | { path: string }
  | { stream: ReadableStream<Uint8Array>; size?: number }
  | { buffer: Uint8Array }

interface FileMeta {
  id: string
  bindingId?: string
  jobId?: string
  filename?: string
  contentType?: string
  size?: number
  status?: string        // 'pending' | 'active' | 'deleted' ...
  cleanupRule?: string
  expiresAt?: string     // ISO 8601
  createdAt?: string
}

interface PresignedUpload {
  fileId: string
  uploadUrl: string             // 짧은 만료 PUT URL
  uploadHeaders?: Record<string, string>
  expiresInSeconds?: number
}

interface LogItem {
  seq: number                   // 잡 안에서 단조 증가
  stream: 'raw' | 'system'      // raw = stdout/stderr, system = SDK 메타
  content: string
  stepName?: string
  level?: 'info' | 'warn' | 'error'   // system 스트림에서 주로 사용
}

interface JobResult {
  status: 'running' | 'success' | 'failed' | 'timeout' | 'rejected'
  exitCode?: number
  errorMessage?: string
  output?: unknown
  rejection?: Rejection
}

import { JobResult } from '@deplite/sdk'
 
JobResult.success({ exitCode: 0, output: { url } })
JobResult.failed({ exitCode: 1, errorMessage: 'build failed' })
JobResult.timeout()
JobResult.rejected({ reason: 'rate_limited', retryAfterSeconds: 120 })

interface Rejection {
  reason: string                // Agent가 보고한 자유 형식 사유 (예: 'rate_limited')
  limitType?: string
  retryAfterSeconds?: number
  bypassedLimits?: string[]
}

interface WorkflowReport {
  name: string
  verboseSteps?: string[]       // step 이름 목록 (메타데이터만)
  secretsKeys?: string[]        // 사용하는 시크릿 키 이름 목록
}

class DepliteError extends Error {
  readonly cause?: unknown
}

class DepliteApiError extends DepliteError {
  readonly statusCode: number
  readonly body: string
}

class DepliteAuthError extends DepliteApiError {
  // 401 또는 403
}

import { DepliteAuthError, DepliteApiError, DepliteError } from '@deplite/sdk'
 
try {
  await deplite.triggers.run({ triggerId, params: {} })
} catch (err) {
  if (err instanceof DepliteAuthError) {
    // 토큰 회수·교체 필요. 재시도 무의미
  } else if (err instanceof DepliteApiError) {
    if (err.statusCode === 429 || err.statusCode >= 500) {
      // 백오프 후 재시도
    }
  } else if (err instanceof DepliteError) {
    // 네트워크·키·디스크
  } else throw err
}