@transloadit/node 4.5.1 → 4.7.0

package/src/cli/commands/docs.ts

@@ -0,0 +1,68 @@
+import { Option } from 'clipanion'
+import { getRobotHelp, isKnownRobot, listRobots } from '../../robots.ts'
+import { UnauthenticatedCommand } from './BaseCommand.ts'
+
+const splitRobotArgs = (values: string[]): string[] => {
+  const out: string[] = []
+  for (const value of values) {
+    for (const part of value.split(',')) {
+      const trimmed = part.trim()
+      if (trimmed) out.push(trimmed)
+    }
+  }
+  return out
+}
+
+export class DocsRobotsListCommand extends UnauthenticatedCommand {
+  static override paths = [['docs', 'robots', 'list']]
+
+  search = Option.String('--search', { description: 'Filter by substring match.' })
+  category = Option.String('--category', { description: 'Filter by category (service slug).' })
+  limit = Option.String('--limit', { description: 'Max results (default: 20).' })
+  cursor = Option.String('--cursor', { description: 'Pagination cursor.' })
+
+  protected override run(): Promise<number | undefined> {
+    const limitNum = this.limit ? Number.parseInt(this.limit, 10) : undefined
+    const result = listRobots({
+      search: this.search,
+      category: this.category,
+      limit: Number.isFinite(limitNum as number) ? (limitNum as number) : undefined,
+      cursor: this.cursor,
+    })
+
+    this.output.print(result.robots.map((r) => `${r.name}  ${r.summary}`).join('\n'), {
+      robots: result.robots,
+      nextCursor: result.nextCursor,
+    })
+
+    return Promise.resolve(0)
+  }
+}
+
+export class DocsRobotsGetCommand extends UnauthenticatedCommand {
+  static override paths = [['docs', 'robots', 'get']]
+
+  robots = Option.Rest({ required: 1 })
+
+  protected override run(): Promise<number | undefined> {
+    const requested = splitRobotArgs(this.robots)
+    const robots = []
+    const notFound: string[] = []
+
+    for (const robotName of requested) {
+      if (!isKnownRobot(robotName)) {
+        notFound.push(robotName)
+        continue
+      }
+      const help = getRobotHelp({ robotName, detailLevel: 'full' })
+      robots.push(help)
+    }
+
+    this.output.print(robots.length === 1 ? robots[0] : robots, {
+      robots,
+      notFound,
+    })
+
+    return Promise.resolve(notFound.length > 0 ? 1 : 0)
+  }
+}

package/src/cli/commands/index.ts

@@ -14,9 +14,8 @@ import {
 import { SignatureCommand, SmartCdnSignatureCommand } from './auth.ts'
 
 import { BillsGetCommand } from './bills.ts'
-
+import { DocsRobotsGetCommand, DocsRobotsListCommand } from './docs.ts'
 import { NotificationsReplayCommand } from './notifications.ts'
-
 import {
   TemplatesCreateCommand,
   TemplatesDeleteCommand,
@@ -67,5 +66,9 @@ export function createCli(): Cli {
   // Uploads commands
   cli.register(UploadCommand)
 
+  // Documentation commands (offline metadata)
+  cli.register(DocsRobotsListCommand)
+  cli.register(DocsRobotsGetCommand)
+
   return cli
 }

package/src/cli/commands/templates.ts

@@ -43,6 +43,8 @@ interface TemplateListOptions {
   order?: 'asc' | 'desc'
   sort?: string
   fields?: string[]
+  includeBuiltin?: 'all' | 'latest' | 'exclusively-all' | 'exclusively-latest'
+  includeContent?: boolean
 }
 
 export interface TemplateSyncOptions {
@@ -162,36 +164,61 @@ const TemplateIdSchema = z.object({
   id: z.string(),
 })
 
-function list(
+const INCLUDE_BUILTIN_VALUES = ['all', 'latest', 'exclusively-all', 'exclusively-latest'] as const
+
+const isIncludeBuiltinValue = (value: string): value is (typeof INCLUDE_BUILTIN_VALUES)[number] => {
+  return (INCLUDE_BUILTIN_VALUES as readonly string[]).includes(value)
+}
+
+async function list(
   output: IOutputCtl,
   client: Transloadit,
-  { before, after, order, sort, fields }: TemplateListOptions,
-): void {
-  const stream = client.streamTemplates({
-    todate: before,
-    fromdate: after,
-    order,
-    sort: sort as 'id' | 'name' | 'created' | 'modified' | undefined,
-  })
+  { before, after, order, sort, fields, includeBuiltin, includeContent }: TemplateListOptions,
+): Promise<void> {
+  // The CLI lists "all templates". Using listTemplates with pagination keeps this
+  // compatible with include_builtin and with "include content" (optional N+1 fetch).
+  const pagesize = 50
+  let page = 1
+
+  while (true) {
+    const response = await client.listTemplates({
+      page,
+      pagesize,
+      todate: before,
+      fromdate: after,
+      order,
+      sort: sort as 'id' | 'name' | 'created' | 'modified' | undefined,
+      include_builtin: includeBuiltin,
+    })
 
-  stream.on('readable', () => {
-    const template: unknown = stream.read()
-    if (template == null) return
+    const items = response.items ?? []
+    if (items.length === 0) break
 
-    const parsed = TemplateIdSchema.safeParse(template)
-    if (!parsed.success) return
+    for (const item of items) {
+      const parsed = TemplateIdSchema.safeParse(item)
+      if (!parsed.success) continue
 
-    if (fields == null) {
-      output.print(parsed.data.id, template)
-    } else {
-      const templateRecord = template as Record<string, unknown>
-      output.print(fields.map((field) => templateRecord[field]).join(' '), template)
+      let template: unknown = item
+      if (includeContent) {
+        try {
+          const full = await client.getTemplate(parsed.data.id)
+          template = { ...item, content: full.content }
+        } catch (err) {
+          output.error(formatAPIError(err))
+        }
+      }
+
+      if (fields == null) {
+        output.print(parsed.data.id, template)
+      } else {
+        const templateRecord = template as Record<string, unknown>
+        output.print(fields.map((field) => templateRecord[field]).join(' '), template)
+      }
     }
-  })
 
-  stream.on('error', (err: unknown) => {
-    output.error(formatAPIError(err))
-  })
+    if (items.length < pagesize) break
+    page += 1
+  }
 }
 
 export async function sync(
@@ -490,6 +517,17 @@ export class TemplatesListCommand extends AuthenticatedCommand {
     description: 'Comma-separated list of fields to return for each template',
   })
 
+  includeBuiltin = Option.String('--include-builtin', {
+    description:
+      `Include builtin templates: ${INCLUDE_BUILTIN_VALUES.join(', ')}. ` +
+      'Omit to list only owned templates.',
+  })
+
+  includeContent = Option.Boolean('--include-content', false, {
+    description:
+      'Include template steps/content in the list output (may make extra API requests per template).',
+  })
+
   protected async run(): Promise<number | undefined> {
     if (this.sort && !['id', 'name', 'created', 'modified'].includes(this.sort)) {
       this.output.error('invalid argument for --sort')
@@ -501,6 +539,16 @@ export class TemplatesListCommand extends AuthenticatedCommand {
       return 1
     }
 
+    const includeBuiltinRaw = this.includeBuiltin
+    let includeBuiltin: TemplateListOptions['includeBuiltin']
+    if (includeBuiltinRaw) {
+      if (!isIncludeBuiltinValue(includeBuiltinRaw)) {
+        this.output.error('invalid argument for --include-builtin')
+        return 1
+      }
+      includeBuiltin = includeBuiltinRaw
+    }
+
     const fieldList = this.fields ? this.fields.split(',') : undefined
 
     await list(this.output, this.client, {
@@ -509,6 +557,8 @@ export class TemplatesListCommand extends AuthenticatedCommand {
       sort: this.sort,
       order: this.order as 'asc' | 'desc' | undefined,
       fields: fieldList,
+      includeBuiltin,
+      includeContent: this.includeContent,
     })
     return undefined
   }

package/src/robots.ts

@@ -36,7 +36,7 @@ export type RobotHelp = {
 
 export type RobotHelpOptions = {
   robotName: string
-  detailLevel?: 'summary' | 'params' | 'examples'
+  detailLevel?: 'summary' | 'params' | 'examples' | 'full'
 }
 
 type RobotsMetaMap = typeof robotsMeta
@@ -299,11 +299,11 @@ export const getRobotHelp = (options: RobotHelpOptions): RobotHelp => {
   const help: RobotHelp = {
     name: path,
     summary,
-    requiredParams: detailLevel === 'params' ? params.required : [],
-    optionalParams: detailLevel === 'params' ? params.optional : [],
+    requiredParams: detailLevel === 'params' || detailLevel === 'full' ? params.required : [],
+    optionalParams: detailLevel === 'params' || detailLevel === 'full' ? params.optional : [],
   }
 
-  if (detailLevel === 'examples' && meta?.example_code) {
+  if ((detailLevel === 'examples' || detailLevel === 'full') && meta?.example_code) {
     const snippet = isRecord(meta.example_code) ? meta.example_code : {}
     help.examples = [
       {
@@ -315,3 +315,11 @@ export const getRobotHelp = (options: RobotHelpOptions): RobotHelp => {
 
   return help
 }
+
+export const isKnownRobot = (robotName: string): boolean => {
+  const { byPath, byName } = getMetaIndex()
+  const schemaIndex = getSchemaIndex()
+
+  const path = resolveRobotPath(robotName)
+  return byPath.has(path) || byName.has(robotName) || schemaIndex.has(path)
+}