feat: add GET /templates/{templateID}/tags to JS and Python SDKs

.changeset/get-template-tags.md

@@ -0,0 +1,6 @@
+---
+'e2b': patch
+'@e2b/python-sdk': patch
+---
+
+Add `getTags`/`get_tags` method to list all tags for a template

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

@@ -1,4 +1,4 @@
-import { ApiClient, handleApiError, paths } from '../api'
+import { ApiClient, handleApiError, paths, components } from '../api'
 import { stripAnsi } from '../utils'
 import { BuildError, FileUploadError, TemplateError } from '../errors'
 import { LogEntry } from './logger'
@@ -7,6 +7,7 @@ import {
   BuildStatusReason,
   TemplateBuildStatus,
   TemplateBuildStatusResponse,
+  TemplateTag,
   TemplateTagInfo,
 } from './types'
 
@@ -358,3 +359,31 @@ export async function removeTags(
     throw error
   }
 }
+
+export async function getTemplateTags(
+  client: ApiClient,
+  { templateID }: { templateID: string }
+): Promise<TemplateTag[]> {
+  const res = await client.api.GET('/templates/{templateID}/tags', {
+    params: {
+      path: {
+        templateID,
+      },
+    },
+  })
+
+  const error = handleApiError(res, TemplateError)
+  if (error) {
+    throw error
+  }
+
+  if (!res.data) {
+    throw new TemplateError('Failed to get template tags')
+  }
+
+  return res.data.map((item: components['schemas']['TemplateTag']) => ({
+    tag: item.tag,
+    buildId: item.buildID,
+    createdAt: new Date(item.createdAt),
+  }))
+}

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

@@ -6,6 +6,7 @@ import { runtime } from '../utils'
 import {
   assignTags,
   checkAliasExists,
+  getTemplateTags,
   removeTags,
   getBuildStatus,
   getFileUploadLink,
@@ -34,6 +35,7 @@ import {
   TemplateFinal,
   TemplateFromImage,
   TemplateOptions,
+  TemplateTag,
   TemplateTagInfo,
 } from './types'
 import {
@@ -371,6 +373,30 @@ export class TemplateBase
     return removeTags(client, { name, tags: normalizedTags })
   }
 
+  /**
+   * Get all tags for a template.
+   *
+   * @param templateId Template ID or name
+   * @param options Authentication options
+   * @returns Array of tag details including tag name, buildId, and creation date
+   *
+   * @example
+   * ```ts
+   * const tags = await Template.getTags('my-template')
+   * for (const tag of tags) {
+   *   console.log(`Tag: ${tag.tag}, Build: ${tag.buildId}, Created: ${tag.createdAt}`)
+   * }
+   * ```
+   */
+  static async getTags(
+    templateId: string,
+    options?: ConnectionOpts
+  ): Promise<TemplateTag[]> {
+    const config = new ConnectionConfig(options)
+    const client = new ApiClient(config)
+    return getTemplateTags(client, { templateID: templateId })
+  }
+
   fromDebianImage(variant: string = 'stable'): TemplateBuilder {
     return this.fromImage(`debian:${variant}`)
   }
@@ -1265,6 +1291,7 @@ Template.exists = TemplateBase.exists
 Template.aliasExists = TemplateBase.aliasExists
 Template.assignTags = TemplateBase.assignTags
 Template.removeTags = TemplateBase.removeTags
+Template.getTags = TemplateBase.getTags
 Template.toJSON = TemplateBase.toJSON
 Template.toDockerfile = TemplateBase.toDockerfile
 
@@ -1279,5 +1306,6 @@ export type {
   TemplateBuildStatus,
   TemplateBuildStatusResponse,
   TemplateClass,
+  TemplateTag,
   TemplateTagInfo,
 } from './types'

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

@@ -158,6 +158,24 @@ export type TemplateTagInfo = {
   tags: string[]
 }
 
+/**
+ * Detailed information about a single template tag.
+ */
+export type TemplateTag = {
+  /**
+   * Name of the tag.
+   */
+  tag: string
+  /**
+   * Build identifier associated with this tag.
+   */
+  buildId: string
+  /**
+   * When this tag was assigned.
+   */
+  createdAt: Date
+}
+
 /**
  * Types of instructions that can be used in a template.
  */

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

@@ -18,6 +18,28 @@ const mockHandlers = [
       tags: tags,
     })
   }),
+  // Get template tags endpoint
+  http.get(apiUrl('/templates/:templateID/tags'), ({ params }) => {
+    const { templateID } = params
+    if (templateID === 'nonexistent') {
+      return HttpResponse.json(
+        { message: 'Template not found' },
+        { status: 404 }
+      )
+    }
+    return HttpResponse.json([
+      {
+        tag: 'v1.0',
+        buildID: '00000000-0000-0000-0000-000000000000',
+        createdAt: '2024-01-15T10:30:00Z',
+      },
+      {
+        tag: 'latest',
+        buildID: '11111111-1111-1111-1111-111111111111',
+        createdAt: '2024-01-16T12:00:00Z',
+      },
+    ])
+  }),
   // Bulk delete endpoint
   http.delete(apiUrl('/templates/tags'), async ({ request }) => {
     const { name } = (await request.clone().json()) as {
@@ -81,6 +103,23 @@ describe('Template tags unit tests', () => {
       ).rejects.toThrow()
     })
   })
+
+  describe('Template.getTags', () => {
+    test('returns tags for a template', async () => {
+      const tags = await Template.getTags('my-template-id')
+      expect(tags).toHaveLength(2)
+      expect(tags[0].tag).toBe('v1.0')
+      expect(tags[0].buildId).toBe('00000000-0000-0000-0000-000000000000')
+      expect(tags[0].createdAt).toBeInstanceOf(Date)
+      expect(tags[1].tag).toBe('latest')
+      expect(tags[1].buildId).toBe('11111111-1111-1111-1111-111111111111')
+      expect(tags[1].createdAt).toBeInstanceOf(Date)
+    })
+
+    test('handles 404 for nonexistent template', async () => {
+      await expect(Template.getTags('nonexistent')).rejects.toThrow()
+    })
+  })
 })
 
 // Integration tests

packages/python-sdk/e2b/__init__.py

@@ -103,6 +103,7 @@
     CopyItem,
     TemplateBuildStatus,
     TemplateBuildStatusResponse,
+    TemplateTag,
     TemplateTagInfo,
 )
 from .template_async.main import AsyncTemplate
@@ -174,6 +175,7 @@
     "BuildStatusReason",
     "TemplateBuildStatus",
     "TemplateBuildStatusResponse",
+    "TemplateTag",
     "TemplateTagInfo",
     "ReadyCmd",
     "wait_for_file",