feat: add template background build helpers (#1011)

<!-- CURSOR_SUMMARY -->
> [!NOTE]
> Add background template build APIs and build status retrieval to
JS/Python SDKs, change build methods to return BuildInfo, and add tests.
> 
> - **JS SDK (templates)**:
> - Add `Template.buildInBackground` to start builds without waiting and
return `BuildInfo`.
> - Add `Template.getBuildStatus` with optional `logsOffset`; expose
`GetBuildStatusResponse`.
> - Change `Template.build` to return `BuildInfo` and then wait for
completion; refactor internal `build(...)` to accept `ApiClient` and
return identifiers.
> - Add types `AuthOptions`, `BuildInfo`, `GetBuildStatusOptions`; make
`logsOffset` optional in `getBuildStatus` input; update tests with
`backgroundBuild.test.ts`.
> - **Python SDK (templates)**:
> - Introduce `BuildInfo` dataclass;
`Template.build`/`AsyncTemplate.build` now return `BuildInfo`.
> - Add `Template.build_in_background` /
`AsyncTemplate.build_in_background` and `Template.get_build_status` /
`AsyncTemplate.get_build_status`; factor shared `_build`.
> - Export `BuildInfo` in `__init__.py`; add sync/async background build
tests.
> - **Meta**:
>   - Add changeset for patch releases.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
a47f70e. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: dobrac

.changeset/happy-bobcats-unite.md

@@ -0,0 +1,6 @@
+---
+'@e2b/python-sdk': patch
+'e2b': patch
+---
+
+add background template build options

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

@@ -24,7 +24,7 @@ type TriggerBuildInput = {
 type GetBuildStatusInput = {
   templateID: string
   buildID: string
-  logsOffset: number
+  logsOffset?: number
 }
 
 export type GetBuildStatusResponse =
@@ -154,7 +154,7 @@ export async function triggerBuild(
 export async function getBuildStatus(
   client: ApiClient,
   { templateID, buildID, logsOffset }: GetBuildStatusInput
-) {
+): Promise<GetBuildStatusResponse> {
   const buildStatusRes = await client.api.GET(
     '/templates/{templateID}/builds/{buildID}/status',
     {

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

@@ -4,6 +4,8 @@ import { ConnectionConfig } from '../connectionConfig'
 import { BuildError } from '../errors'
 import { runtime } from '../utils'
 import {
+  getBuildStatus,
+  GetBuildStatusResponse,
   getFileUploadLink,
   requestBuild,
   triggerBuild,
@@ -16,8 +18,10 @@ import { parseDockerfile } from './dockerfileParser'
 import { LogEntry, LogEntryEnd, LogEntryStart } from './logger'
 import { ReadyCmd, waitForFile } from './readycmd'
 import {
+  BuildInfo,
   BuildOptions,
   CopyItem,
+  GetBuildStatusOptions,
   Instruction,
   InstructionType,
   McpServerName,
@@ -113,15 +117,94 @@ export class TemplateBase
   static async build(
     template: TemplateClass,
     options: BuildOptions
-  ): Promise<void> {
+  ): Promise<BuildInfo> {
     try {
       options.onBuildLogs?.(new LogEntryStart(new Date(), 'Build started'))
-      return await (template as TemplateBase).build(options)
+      const baseTemplate = template as TemplateBase
+
+      const config = new ConnectionConfig({
+        domain: options.domain,
+        apiKey: options.apiKey,
+      })
+      const client = new ApiClient(config)
+
+      const data = await baseTemplate.build(client, options)
+
+      options.onBuildLogs?.(
+        new LogEntry(new Date(), 'info', 'Waiting for logs...')
+      )
+
+      await waitForBuildFinish(client, {
+        templateID: data.templateId,
+        buildID: data.buildId,
+        onBuildLogs: options.onBuildLogs,
+        logsRefreshFrequency: baseTemplate.logsRefreshFrequency,
+        stackTraces: baseTemplate.stackTraces,
+      })
+
+      return data
     } finally {
       options.onBuildLogs?.(new LogEntryEnd(new Date(), 'Build finished'))
     }
   }
 
+  /**
+   * Build and deploy a template to E2B infrastructure.
+   *
+   * @param template The template to build
+   * @param options Build configuration options
+   *
+   * @example
+   * ```ts
+   * const template = Template().fromPythonImage('3')
+   * const data = await Template.buildInBackground(template, {
+   *   alias: 'my-python-env',
+   *   cpuCount: 2,
+   *   memoryMB: 1024
+   * })
+   * ```
+   */
+  static async buildInBackground(
+    template: TemplateClass,
+    options: BuildOptions
+  ): Promise<BuildInfo> {
+    const config = new ConnectionConfig({
+      domain: options.domain,
+      apiKey: options.apiKey,
+    })
+    const client = new ApiClient(config)
+
+    return await (template as TemplateBase).build(client, options)
+  }
+
+  /**
+   * Get the status of a build.
+   *
+   * @param data Build identifiers
+   * @param options Authentication options
+   *
+   * @example
+   * ```ts
+   * const status = await Template.getBuildStatus(data, { logsOffset: 0 })
+   * ```
+   */
+  static async getBuildStatus(
+    data: Pick<BuildInfo, 'templateId' | 'buildId'>,
+    options?: GetBuildStatusOptions
+  ): Promise<GetBuildStatusResponse> {
+    const config = new ConnectionConfig({
+      domain: options?.domain,
+      apiKey: options?.apiKey,
+    })
+    const client = new ApiClient(config)
+
+    return await getBuildStatus(client, {
+      templateID: data.templateId,
+      buildID: data.buildId,
+      logsOffset: options?.logsOffset,
+    })
+  }
+
   fromDebianImage(variant: string = 'stable'): TemplateBuilder {
     return this.fromImage(`debian:${variant}`)
   }
@@ -768,16 +851,14 @@ export class TemplateBase
   /**
    * Internal implementation of the template build process.
    *
+   * @param client API client for communicating with E2B backend
    * @param options Build configuration options
    * @throws BuildError if the build fails
    */
-  private async build(options: BuildOptions): Promise<void> {
-    const config = new ConnectionConfig({
-      domain: options.domain,
-      apiKey: options.apiKey,
-    })
-    const client = new ApiClient(config)
-
+  private async build(
+    client: ApiClient,
+    options: BuildOptions
+  ): Promise<BuildInfo> {
     if (options.skipCache) {
       this.force = true
     }
@@ -880,17 +961,11 @@ export class TemplateBase
       template: this.serialize(instructionsWithHashes),
     })
 
-    options.onBuildLogs?.(
-      new LogEntry(new Date(), 'info', 'Waiting for logs...')
-    )
-
-    await waitForBuildFinish(client, {
-      templateID,
-      buildID,
-      onBuildLogs: options.onBuildLogs,
-      logsRefreshFrequency: this.logsRefreshFrequency,
-      stackTraces: this.stackTraces,
-    })
+    return {
+      alias: options.alias,
+      templateId: templateID,
+      buildId: buildID,
+    }
   }
 
   /**
@@ -989,12 +1064,16 @@ export function Template(options?: TemplateOptions): TemplateFromImage {
 }
 
 Template.build = TemplateBase.build
+Template.buildInBackground = TemplateBase.buildInBackground
+Template.getBuildStatus = TemplateBase.getBuildStatus
 Template.toJSON = TemplateBase.toJSON
 Template.toDockerfile = TemplateBase.toDockerfile
 
 export type {
+  BuildInfo,
   BuildOptions,
   CopyItem,
+  GetBuildStatusOptions,
   McpServerName,
   TemplateBuilder,
   TemplateClass,

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

@@ -48,9 +48,9 @@ export type BasicBuildOptions = {
 }
 
 /**
- * Options for building a template with authentication.
+ * Authentication options for E2B API.
  */
-export type BuildOptions = BasicBuildOptions & {
+export type AuthOptions = {
   /**
    * E2B API key for authentication.
    */
@@ -61,6 +61,25 @@ export type BuildOptions = BasicBuildOptions & {
   domain?: string
 }
 
+/**
+ * Options for building a template with authentication.
+ */
+export type BuildOptions = AuthOptions & BasicBuildOptions
+
+/**
+ * Information about a built template.
+ */
+export type BuildInfo = {
+  alias: string
+  templateId: string
+  buildId: string
+}
+
+/**
+ * Response from getting build status.
+ */
+export type GetBuildStatusOptions = AuthOptions & { logsOffset?: number }
+
 /**
  * Types of instructions that can be used in a template.
  */

packages/js-sdk/tests/setup.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto'
 import { test as base } from 'vitest'
-import { LogEntry, Sandbox, Template, TemplateClass } from '../src'
+import { BuildInfo, LogEntry, Sandbox, Template, TemplateClass } from '../src'
 import { template } from './template'
 
 interface SandboxFixture {
@@ -14,7 +14,7 @@ interface BuildTemplateFixture {
     template: TemplateClass,
     options?: { skipCache?: boolean },
     onBuildLogs?: (logEntry: LogEntry) => void
-  ) => Promise<void>
+  ) => Promise<BuildInfo>
 }
 
 function buildTemplate(

packages/js-sdk/tests/template/backgroundBuild.test.ts

@@ -0,0 +1,26 @@
+import { randomUUID } from 'node:crypto'
+import { expect, test } from 'vitest'
+import { Template, waitForTimeout } from '../../src'
+
+test('build template in background', async () => {
+  const template = Template()
+    .fromImage('ubuntu:22.04')
+    .skipCache()
+    .runCmd('sleep 5') // Add a delay to ensure build takes time
+    .setStartCmd('echo "Hello"', waitForTimeout(10_000))
+
+  const alias = `e2b-test-${randomUUID()}`
+
+  const buildInfo = await Template.buildInBackground(template, {
+    alias,
+    cpuCount: 1,
+    memoryMB: 1024,
+  })
+
+  // Should return quickly (within a few seconds), not wait for the full build
+  expect(buildInfo).toBeDefined()
+
+  // Verify the build is actually running
+  const status = await Template.getBuildStatus(buildInfo)
+  expect(status.status).toEqual('building')
+}, 10_000)

packages/python-sdk/e2b/__init__.py

@@ -92,7 +92,7 @@
     wait_for_process,
     wait_for_timeout,
 )
-from .template.types import CopyItem
+from .template.types import CopyItem, BuildInfo
 from .template_async.main import AsyncTemplate
 from .template_sync.main import Template
 
@@ -150,6 +150,7 @@
     "TemplateBase",
     "TemplateClass",
     "CopyItem",
+    "BuildInfo",
     "ReadyCmd",
     "wait_for_file",
     "wait_for_url",

packages/python-sdk/e2b/template/types.py

@@ -1,7 +1,7 @@
+from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
-from typing import List, Optional, TypedDict, Union
-from typing import Literal
+from typing import List, Literal, Optional, TypedDict, Union
 
 from typing_extensions import NotRequired
 
@@ -92,3 +92,14 @@ class TemplateType(TypedDict):
     readyCmd: NotRequired[str]
     steps: List[Instruction]
     force: bool
+
+
+@dataclass
+class BuildInfo:
+    """
+    Information about a built template.
+    """
+
+    alias: str
+    template_id: str
+    build_id: str