Templates SDK JS - Use classes instead of interface

packages/js-sdk/package.json

@@ -90,8 +90,12 @@
     "@connectrpc/connect": "2.0.0-rc.3",
     "@connectrpc/connect-web": "2.0.0-rc.3",
     "compare-versions": "^6.1.0",
+    "dockerfile-ast": "^0.7.1",
+    "glob": "^11.0.3",
     "openapi-fetch": "^0.9.7",
-    "platform": "^1.3.6"
+    "platform": "^1.3.6",
+    "strip-ansi": "^7.1.0",
+    "tar": "^7.4.3"
   },
   "engines": {
     "node": ">=18"

packages/js-sdk/src/api/index.ts

@@ -7,12 +7,23 @@ import { AuthenticationError, RateLimitError, SandboxError } from '../errors'
 import { createApiLogger } from '../logs'
 
 export function handleApiError(
-  response: FetchResponse<any, any, any>
+  response: FetchResponse<any, any, any>,
+  errorClass: new (message: string) => Error = SandboxError
 ): Error | undefined {
   if (!response.error) {
     return
   }
 
+  if (response.response.status === 401) {
+    const message = 'Unauthorized, please check your credentials.'
+    const content = response.error?.message ?? response.error
+
+    if (content) {
+      return new AuthenticationError(`${message} - ${content}`)
+    }
+    return new AuthenticationError(message)
+  }
+
   if (response.response.status === 429) {
     const message = 'Rate limit exceeded, please try again later'
     const content = response.error?.message ?? response.error
@@ -24,7 +35,7 @@ export function handleApiError(
   }
 
   const message = response.error?.message ?? response.error
-  return new SandboxError(`${response.response.status}: ${message}`)
+  return new errorClass(`${response.response.status}: ${message}`)
 }
 
 /**

packages/js-sdk/src/api/metadata.ts

@@ -1,55 +1,10 @@
 import platform from 'platform'
 
 import { version } from '../../package.json'
+import { runtime, runtimeVersion } from '../utils'
 
 export { version }
 
-declare let window: any
-
-type Runtime =
-  | 'node'
-  | 'browser'
-  | 'deno'
-  | 'bun'
-  | 'vercel-edge'
-  | 'cloudflare-worker'
-  | 'unknown'
-
-function getRuntime(): { runtime: Runtime; version: string } {
-  // @ts-ignore
-  if ((globalThis as any).Bun) {
-    // @ts-ignore
-    return { runtime: 'bun', version: globalThis.Bun.version }
-  }
-
-  // @ts-ignore
-  if ((globalThis as any).Deno) {
-    // @ts-ignore
-    return { runtime: 'deno', version: globalThis.Deno.version.deno }
-  }
-
-  if ((globalThis as any).process?.release?.name === 'node') {
-    return { runtime: 'node', version: platform.version || 'unknown' }
-  }
-
-  // @ts-ignore
-  if (typeof EdgeRuntime === 'string') {
-    return { runtime: 'vercel-edge', version: 'unknown' }
-  }
-
-  if ((globalThis as any).navigator?.userAgent === 'Cloudflare-Workers') {
-    return { runtime: 'cloudflare-worker', version: 'unknown' }
-  }
-
-  if (typeof window !== 'undefined') {
-    return { runtime: 'browser', version: platform.version || 'unknown' }
-  }
-
-  return { runtime: 'unknown', version: 'unknown' }
-}
-
-export const { runtime, version: runtimeVersion } = getRuntime()
-
 export const defaultHeaders = {
   browser: (typeof window !== 'undefined' && platform.name) || 'unknown',
   lang: 'js',

packages/js-sdk/src/envd/rpc.ts

@@ -1,5 +1,5 @@
 import { Code, ConnectError } from '@connectrpc/connect'
-import { runtime } from '../api/metadata'
+import { runtime } from '../utils'
 import { defaultUsername } from '../connectionConfig'
 
 import {

packages/js-sdk/src/errors.ts

@@ -68,7 +68,7 @@ export class NotFoundError extends SandboxError {
 /**
  * Thrown when authentication fails.
  */
-export class AuthenticationError extends SandboxError {
+export class AuthenticationError extends Error {
   constructor(message: any) {
     super(message)
     this.name = 'AuthenticationError'
@@ -94,3 +94,17 @@ export class RateLimitError extends SandboxError {
     this.name = 'RateLimitError'
   }
 }
+
+export class BuildError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'BuildError'
+  }
+}
+
+export class FileUploadError extends BuildError {
+  constructor(message: string) {
+    super(message)
+    this.name = 'FileUploadError'
+  }
+}

packages/js-sdk/src/index.ts

@@ -12,6 +12,8 @@ export {
   TemplateError,
   TimeoutError,
   RateLimitError,
+  BuildError,
+  FileUploadError,
 } from './errors'
 export type { Logger } from './logs'
 
@@ -58,3 +60,5 @@ export type {
 export { Sandbox }
 import { Sandbox } from './sandbox'
 export default Sandbox
+
+export { Template, type TemplateClass, type TemplateBase } from './template'

packages/js-sdk/src/template/buildApi.ts

@@ -0,0 +1,223 @@
+import { ApiClient, paths, handleApiError } from '../api'
+import { BuildError, FileUploadError } from '../errors'
+import { LogEntry } from './types'
+import { tarFileStreamUpload } from './utils'
+import stripAnsi from 'strip-ansi'
+
+type RequestBuildInput = {
+  alias: string
+  cpuCount: number
+  memoryMB: number
+}
+
+type GetFileUploadLinkInput = {
+  templateID: string
+  filesHash: string
+}
+
+type TriggerBuildInput = {
+  templateID: string
+  buildID: string
+  template: TriggerBuildTemplate
+}
+
+type GetBuildStatusInput = {
+  templateID: string
+  buildID: string
+  logsOffset: number
+}
+
+export type GetBuildStatusResponse =
+  paths['/templates/{templateID}/builds/{buildID}/status']['get']['responses']['200']['content']['application/json']
+
+export type TriggerBuildTemplate =
+  paths['/v2/templates/{templateID}/builds/{buildID}']['post']['requestBody']['content']['application/json']
+
+export async function requestBuild(
+  client: ApiClient,
+  { alias, cpuCount, memoryMB }: RequestBuildInput
+) {
+  const requestBuildRes = await client.api.POST('/v2/templates', {
+    body: {
+      alias,
+      cpuCount,
+      memoryMB,
+    },
+  })
+
+  const error = handleApiError(requestBuildRes, BuildError)
+  if (error) {
+    throw error
+  }
+
+  if (!requestBuildRes.data) {
+    throw new BuildError('Failed to request build')
+  }
+
+  return requestBuildRes.data
+}
+
+export async function getFileUploadLink(
+  client: ApiClient,
+  { templateID, filesHash }: GetFileUploadLinkInput
+) {
+  const fileUploadLinkRes = await client.api.GET(
+    '/templates/{templateID}/files/{hash}',
+    {
+      params: {
+        path: {
+          templateID,
+          hash: filesHash,
+        },
+      },
+    }
+  )
+
+  const error = handleApiError(fileUploadLinkRes, FileUploadError)
+  if (error) {
+    throw error
+  }
+
+  if (!fileUploadLinkRes.data) {
+    throw new FileUploadError('Failed to get file upload link')
+  }
+
+  return fileUploadLinkRes.data
+}
+
+export async function uploadFile(options: {
+  fileName: string
+  fileContextPath: string
+  url: string
+}) {
+  const { fileName, url, fileContextPath } = options
+  const { contentLength, uploadStream } = await tarFileStreamUpload(
+    fileName,
+    fileContextPath
+  )
+
+  // The compiler assumes this is Web fetch API, but it's actually Node.js fetch API
+  const res = await fetch(url, {
+    method: 'PUT',
+    // @ts-expect-error
+    body: uploadStream,
+    headers: {
+      'Content-Length': contentLength.toString(),
+    },
+    duplex: 'half',
+  })
+
+  if (!res.ok) {
+    throw new FileUploadError(
+      `Failed to upload file: ${res.statusText} ${res.status}`
+    )
+  }
+}
+
+export async function triggerBuild(
+  client: ApiClient,
+  { templateID, buildID, template }: TriggerBuildInput
+) {
+  const triggerBuildRes = await client.api.POST(
+    '/v2/templates/{templateID}/builds/{buildID}',
+    {
+      params: {
+        path: {
+          templateID,
+          buildID,
+        },
+      },
+      body: template,
+    }
+  )
+
+  const error = handleApiError(triggerBuildRes, BuildError)
+  if (error) {
+    throw error
+  }
+}
+
+export async function getBuildStatus(
+  client: ApiClient,
+  { templateID, buildID, logsOffset }: GetBuildStatusInput
+) {
+  const buildStatusRes = await client.api.GET(
+    '/templates/{templateID}/builds/{buildID}/status',
+    {
+      params: {
+        path: {
+          templateID,
+          buildID,
+        },
+        query: {
+          logsOffset,
+        },
+      },
+    }
+  )
+
+  const error = handleApiError(buildStatusRes, BuildError)
+  if (error) {
+    throw error
+  }
+
+  if (!buildStatusRes.data) {
+    throw new BuildError('Failed to get build status')
+  }
+
+  return buildStatusRes.data
+}
+
+export async function waitForBuildFinish(
+  client: ApiClient,
+  {
+    templateID,
+    buildID,
+    onBuildLogs,
+    logsRefreshFrequency,
+  }: {
+    templateID: string
+    buildID: string
+    onBuildLogs?: (logEntry: InstanceType<typeof LogEntry>) => void
+    logsRefreshFrequency: number
+  }
+): Promise<void> {
+  let logsOffset = 0
+  let status: GetBuildStatusResponse['status'] = 'building'
+
+  while (status === 'building') {
+    const buildStatus = await getBuildStatus(client, {
+      templateID,
+      buildID,
+      logsOffset,
+    })
+
+    logsOffset += buildStatus.logEntries.length
+
+    buildStatus.logEntries.forEach(
+      (logEntry: GetBuildStatusResponse['logEntries'][number]) =>
+        onBuildLogs?.(
+          new LogEntry(
+            new Date(logEntry.timestamp),
+            logEntry.level,
+            stripAnsi(logEntry.message)
+          )
+        )
+    )
+
+    status = buildStatus.status
+    switch (status) {
+      case 'ready': {
+        return
+      }
+      case 'error': {
+        throw new BuildError(buildStatus?.reason?.message ?? 'Unknown error')
+      }
+    }
+
+    // Wait for a short period before checking the status again
+    await new Promise((resolve) => setTimeout(resolve, logsRefreshFrequency))
+  }
+
+  throw new BuildError('Unknown build error occurred.')
+}