feat: rename golden templates to builtin

Author: kvz

.changeset/builtin-templates-api.md

@@ -0,0 +1,6 @@
+---
+"@transloadit/mcp-server": minor
+"@transloadit/node": minor
+---
+
+Fetch builtin templates from the API and remove bundled builtin template data.

.changeset/golden-templates-api.md

@@ -2,8 +2,8 @@
   "packageDir": "/home/kvz/code/node-sdk/packages/transloadit",
   "tarball": {
     "filename": "transloadit-4.4.0.tgz",
-    "sizeBytes": 1231681,
-    "sha256": "ec460c59a74d8d0e3ae826819f16b8a12e2134975995341461f99711b58dfd93"
+    "sizeBytes": 1231694,
+    "sha256": "80d6b260663a7dbec0157560788fb2aaa9902b051d07004ba46746815cb404ca"
   },
   "packageJson": {
     "name": "transloadit",
@@ -723,8 +723,8 @@
     },
     {
       "path": "dist/apiTypes.d.ts.map",
-      "sizeBytes": 3668,
-      "sha256": "f3812c67e402777b133ee0676e5b89a569c5e172b15c1322b0a71797793cdbda"
+      "sizeBytes": 3662,
+      "sha256": "0b54ad2511e77feebc1831ff78dbe9c74d7198ac91ad24f8d44f3fd2b19a71dc"
     },
     {
       "path": "dist/apiTypes.js.map",
@@ -2038,13 +2038,13 @@
     },
     {
       "path": "dist/apiTypes.d.ts",
-      "sizeBytes": 3864,
-      "sha256": "326478834139f0974e5f5a37263b3fae8b95622847e87cf4f2c2bc9b48d0bd2a"
+      "sizeBytes": 3881,
+      "sha256": "2069dce5782d8371b6b697336b340d71d0914de9418654155078d27297dc01bf"
     },
     {
       "path": "src/apiTypes.ts",
-      "sizeBytes": 4167,
-      "sha256": "ad038624f0b527b4f406b76a6120a6e27c1659dde28c22cbaee7e3d85f2e99e7"
+      "sizeBytes": 4184,
+      "sha256": "06d958942ffd07d5d63a7f49d50dd492af3fac2f2df32545f7c5b36743d27548"
     },
     {
       "path": "dist/cli/commands/assemblies.d.ts",

docs/fingerprint/transloadit-baseline.json

@@ -118,7 +118,7 @@ If `assembly_url` is provided, the MCP server resumes uploads using Assembly sta
 - `transloadit_lint_assembly_instructions`
 - `transloadit_list_robots`
 - `transloadit_get_robot_help`
-- `transloadit_list_golden_templates`
+- `transloadit_list_builtin_templates`
 
 ## Roadmap
 

packages/mcp-server/README.md

@@ -48,7 +48,7 @@ type ToolExtra = {
 }
 
 const maxBase64Bytes = 512_000
-type GoldenTemplate = {
+type BuiltinTemplate = {
   slug: string
   version: string
   description: string
@@ -144,7 +144,7 @@ const inputFileSchema = z.discriminatedUnion('kind', [
 
 const createAssemblyInputSchema = z.object({
   instructions: z.unknown().optional(),
-  golden_template: z
+  builtin_template: z
     .object({
       slug: z.string(),
       version: z.string().optional(),
@@ -205,9 +205,9 @@ const waitForAssemblyOutputSchema = z.object({
   warnings: z.array(toolMessageSchema).optional(),
 })
 
-const listGoldenTemplatesInputSchema = z.object({})
+const listBuiltinTemplatesInputSchema = z.object({})
 
-const listGoldenTemplatesOutputSchema = z.object({
+const listBuiltinTemplatesOutputSchema = z.object({
   status: z.enum(['ok', 'error']),
   templates: z.array(
     z.object({
@@ -387,11 +387,11 @@ type ApiTemplateRecord = {
   id?: unknown
   name?: unknown
   description?: unknown
-  golden_version?: unknown
+  builtin_version?: unknown
   content?: unknown
 }
 
-const buildGoldenTemplateId = (slug: string, version?: string): string => {
+const buildBuiltinTemplateId = (slug: string, version?: string): string => {
   if (slug.includes('@')) return slug
   if (version) return `${slug}@${version}`
   return slug
@@ -403,20 +403,20 @@ const extractTemplateSteps = (content: unknown): Record<string, unknown> | undef
   return isRecord(steps) ? (steps as Record<string, unknown>) : undefined
 }
 
-const mapGoldenTemplate = (template: ApiTemplateRecord): GoldenTemplate | undefined => {
+const mapBuiltinTemplate = (template: ApiTemplateRecord): BuiltinTemplate | undefined => {
   const slug = isNonEmptyString(template.name)
     ? template.name
     : isNonEmptyString(template.id)
       ? template.id
       : undefined
 
-  if (!slug || !slug.startsWith('~')) return undefined
+  if (!slug || !slug.startsWith('builtin/')) return undefined
 
   const steps = extractTemplateSteps(template.content)
   if (!steps) return undefined
 
-  const version = isNonEmptyString(template.golden_version)
-    ? template.golden_version
+  const version = isNonEmptyString(template.builtin_version)
+    ? template.builtin_version
     : slug.includes('@')
       ? (slug.split('@')[1] ?? '')
       : ''
@@ -429,9 +429,9 @@ const mapGoldenTemplate = (template: ApiTemplateRecord): GoldenTemplate | undefi
   }
 }
 
-const fetchGoldenTemplates = async (client: Transloadit): Promise<GoldenTemplate[]> => {
+const fetchBuiltinTemplates = async (client: Transloadit): Promise<BuiltinTemplate[]> => {
   const response = (await client.listTemplates({
-    include_golden: 'latest',
+    include_builtin: 'exclusively-latest',
     page: 1,
     pagesize: 100,
   })) as {
@@ -440,16 +440,16 @@ const fetchGoldenTemplates = async (client: Transloadit): Promise<GoldenTemplate
 
   const items = Array.isArray(response.items) ? response.items : []
   return items
-    .map((template) => mapGoldenTemplate(template))
-    .filter((template): template is GoldenTemplate => Boolean(template))
+    .map((template) => mapBuiltinTemplate(template))
+    .filter((template): template is BuiltinTemplate => Boolean(template))
 }
 
-const fetchGoldenTemplateContent = async (
+const fetchBuiltinTemplateContent = async (
   client: Transloadit,
   slug: string,
   version?: string,
 ): Promise<TemplateContent | undefined> => {
-  const templateId = buildGoldenTemplateId(slug, version)
+  const templateId = buildBuiltinTemplateId(slug, version)
   const template = (await client.getTemplate(templateId)) as {
     content?: unknown
   }
@@ -524,7 +524,7 @@ export const createTransloaditMcpServer = (
     async (
       {
         instructions,
-        golden_template,
+        builtin_template,
         files,
         fields,
         wait_for_completion,
@@ -537,10 +537,10 @@ export const createTransloaditMcpServer = (
       },
       extra,
     ) => {
-      if (instructions && golden_template) {
+      if (instructions && builtin_template) {
         return buildToolError(
           'mcp_invalid_args',
-          'Provide either instructions or golden_template, not both.',
+          'Provide either instructions or builtin_template, not both.',
           { path: 'instructions' },
         )
       }
@@ -554,22 +554,22 @@ export const createTransloaditMcpServer = (
         const fileInputs = files ?? []
         let params = parseInstructions(instructions) ?? ({} as CreateAssemblyParams)
 
-        if (golden_template) {
-          const templateContent = await fetchGoldenTemplateContent(
+        if (builtin_template) {
+          const templateContent = await fetchBuiltinTemplateContent(
             client,
-            golden_template.slug,
-            golden_template.version,
+            builtin_template.slug,
+            builtin_template.version,
           )
 
           if (!templateContent) {
             return buildToolError(
               'mcp_unknown_template',
-              `Unknown golden template: ${golden_template.slug}`,
-              { path: 'golden_template.slug' },
+              `Unknown builtin template: ${builtin_template.slug}`,
+              { path: 'builtin_template.slug' },
             )
           }
 
-          const overrides = golden_template.overrides
+          const overrides = builtin_template.overrides
           params = mergeTemplateContent(
             templateContent,
             overrides && isRecord(overrides) ? (overrides as Record<string, unknown>) : undefined,
@@ -775,12 +775,12 @@ export const createTransloaditMcpServer = (
   )
 
   server.registerTool(
-    'transloadit_list_golden_templates',
+    'transloadit_list_builtin_templates',
     {
-      title: 'List golden templates',
+      title: 'List builtin templates',
       description: 'Returns curated starter templates with ready-to-run steps.',
-      inputSchema: listGoldenTemplatesInputSchema,
-      outputSchema: listGoldenTemplatesOutputSchema,
+      inputSchema: listBuiltinTemplatesInputSchema,
+      outputSchema: listBuiltinTemplatesOutputSchema,
     },
     async (_args, extra) => {
       const liveClient = createLiveClient(options, extra)
@@ -799,19 +799,20 @@ export const createTransloaditMcpServer = (
       }
 
       try {
-        const templates = await fetchGoldenTemplates(liveClient.client)
+        const templates = await fetchBuiltinTemplates(liveClient.client)
         return buildToolResponse({
           status: 'ok',
           templates,
         })
       } catch (error) {
-        const message = error instanceof Error ? error.message : 'Failed to fetch golden templates.'
+        const message =
+          error instanceof Error ? error.message : 'Failed to fetch builtin templates.'
         return buildToolResponse({
           status: 'error',
           templates: [],
           errors: [
             {
-              code: 'mcp_golden_templates_failed',
+              code: 'mcp_builtin_templates_failed',
               message,
             },
           ],

packages/mcp-server/src/server.ts

@@ -2,7 +2,7 @@ import type { Client } from '@modelcontextprotocol/sdk/client'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 import { createMcpClient, isRecord, parseToolPayload } from './mcp-client.ts'
 
-describe('mcp-server golden templates', { timeout: 20000 }, () => {
+describe('mcp-server builtin templates', { timeout: 20000 }, () => {
   let client: Client
 
   beforeAll(async () => {
@@ -13,9 +13,9 @@ describe('mcp-server golden templates', { timeout: 20000 }, () => {
     await client?.close()
   })
 
-  it('lists golden templates with steps', async () => {
+  it('lists builtin templates with steps', async () => {
     const result = await client.callTool({
-      name: 'transloadit_list_golden_templates',
+      name: 'transloadit_list_builtin_templates',
       arguments: {},
     })
 
@@ -25,8 +25,18 @@ describe('mcp-server golden templates', { timeout: 20000 }, () => {
     expect(Array.isArray(payload.templates)).toBe(true)
 
     const templates = payload.templates as Array<Record<string, unknown>>
-    const hls = templates.find(
-      (template) => template.slug === '~transloadit/encode-hls-video@0.0.1',
+    const builtins = templates.filter((template) =>
+      typeof template.slug === 'string' ? template.slug.startsWith('builtin/') : false,
+    )
+
+    if (process.env.TRANSLOADIT_ENDPOINT?.includes('devdock')) {
+      expect(builtins.length).toBe(2)
+    } else {
+      expect(builtins.length).toBeGreaterThan(0)
+    }
+
+    const hls = builtins.find((template) =>
+      typeof template.slug === 'string' ? template.slug.includes('encode-hls-video') : false,
     )
 
     expect(isRecord(hls)).toBe(true)

…server/test/e2e/golden-templates.test.ts …erver/test/e2e/builtin-templates.test.tspackages/mcp-server/test/e2e/golden-templates.test.ts renamed to packages/mcp-server/test/e2e/builtin-templates.test.ts packages/mcp-server/test/e2e/golden-templates.test.ts renamed to packages/mcp-server/test/e2e/builtin-templates.test.ts

@@ -98,7 +98,7 @@ export type ListTemplatesParams = OptionalAuthParams & {
   fromdate?: string
   todate?: string
   keywords?: string[]
-  include_golden?: 'none' | 'latest' | 'all'
+  include_builtin?: 'exclusively-all' | 'exclusively-latest'
 }
 
 interface TemplateResponseBase {
@@ -114,7 +114,7 @@ export interface ListedTemplate extends TemplateResponseBase {
   created?: string | null
   modified?: string | null
   description?: string
-  golden_version?: string
+  builtin_version?: string
 }
 
 export interface TemplateResponse extends TemplateResponseBase, BaseResponse {}