Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The CDN API allows you to upload and retrieve files from the Lua CDN. Files are stored securely and can be accessed by their unique file ID. 
import { CDN } from 'lua-cli';

// Upload a file
const fileId = await CDN.upload(file);

// Retrieve a file
const file = await CDN.get(fileId);

​
Methods

​
upload

Uploads a file to the CDN. 
const fileId = await CDN.upload(file);
Parameters:
ParameterTypeDescription
fileFileThe File object to upload
Returns: Promise<string> - The unique file ID Example: 
import { CDN } from 'lua-cli';
import { readFileSync } from 'fs';

// From a buffer
const buffer = readFileSync('image.png');
const file = new File([buffer], 'image.png', { type: 'image/png' });
const fileId = await CDN.upload(file);

console.log('Uploaded:', fileId);

​
get

Retrieves a file from the CDN by its ID. 
const file = await CDN.get(fileId);
Parameters:
ParameterTypeDescription
fileIdstringThe unique identifier of the file
Returns: Promise<File> - The File object with name, type, and size properties Example: 
import { CDN } from 'lua-cli';

const file = await CDN.get('abc123-def456');

console.log(file.name);  // filename
console.log(file.type);  // e.g., 'image/png'
console.log(file.size);  // bytes

​
Use Cases

​
Store User Uploads

export class SaveDocumentTool implements LuaTool {
  name = "save_document";
  description = "Save a document to storage";
  inputSchema = z.object({
    content: z.string(),
    filename: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const file = new File(
      [input.content], 
      input.filename, 
      { type: 'text/plain' }
    );
    
    const fileId = await CDN.upload(file);
    
    return {
      success: true,
      fileId,
      message: `Document saved as ${input.filename}`
    };
  }
}

​
Retrieve and Process Files

export class ReadDocumentTool implements LuaTool {
  name = "read_document";
  description = "Read a document from storage";
  inputSchema = z.object({
    fileId: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const file = await CDN.get(input.fileId);
    const content = await file.text();
    
    return {
      success: true,
      filename: file.name,
      content
    };
  }
}

​
Use with AI for Image Analysis

export class AnalyzeImageTool implements LuaTool {
  name = "analyze_image";
  description = "Analyze an image using AI";
  inputSchema = z.object({
    fileId: z.string(),
    question: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const file = await CDN.get(input.fileId);
    const buffer = Buffer.from(await file.arrayBuffer());
    
    const analysis = await AI.generate(
      'You are an image analysis expert.',
      [
        { type: 'text', text: input.question },
        { type: 'image', image: buffer, mediaType: file.type } as any
      ]
    );
    
    return { analysis };
  }
}

​
Re-upload Files

Since CDN.get() returns a File object, you can easily re-upload files: 
// Get existing file
const file = await CDN.get(existingFileId);

// Re-upload (creates a new copy)
const newFileId = await CDN.upload(file);

​
File Properties

The File object returned by CDN.get() has these properties:
PropertyTypeDescription
namestringOriginal filename
typestringMIME type (e.g., image/png)
sizenumberFile size in bytes
And these methods:
MethodReturnsDescription
text()Promise<string>Read as text
arrayBuffer()Promise<ArrayBuffer>Read as binary
stream()ReadableStreamRead as stream

​
Supported File Types

The CDN supports all file types including:
  • Images: PNG, JPEG, GIF, WebP, SVG
  • Documents: PDF, DOC, DOCX, TXT
  • Data: JSON, CSV, XML
  • Audio/Video: MP3, MP4, WAV
  • Archives: ZIP, TAR
Images are automatically optimized with WebP compression while maintaining quality.

​
Best Practices

Include meaningful names when creating Files:
// Good
new File([data], 'invoice-2024-001.pdf', { type: 'application/pdf' })

// Avoid
new File([data], 'file.pdf', { type: 'application/pdf' })
Always specify the correct MIME type:
// Images
{ type: 'image/png' }
{ type: 'image/jpeg' }

// Documents
{ type: 'application/pdf' }
{ type: 'text/plain' }

// Data
{ type: 'application/json' }
Save file IDs in your data for later retrieval:
const fileId = await CDN.upload(file);

await Data.create('documents', {
  title: 'Contract',
  fileId: fileId,  // Store for later
  uploadedAt: new Date().toISOString()
});
Always handle potential errors:
try {
  const file = await CDN.get(fileId);
  return { success: true, file };
} catch (error) {
  return { 
    success: false, 
    error: 'File not found' 
  };
}

​
Complete Example

import { LuaTool, CDN, Data, AI } from 'lua-cli';
import { z } from 'zod';

export class DocumentManagerTool implements LuaTool {
  name = "manage_document";
  description = "Upload, retrieve, or analyze documents";
  inputSchema = z.object({
    action: z.enum(['upload', 'get', 'analyze']),
    fileId: z.string().optional(),
    content: z.string().optional(),
    filename: z.string().optional()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    switch (input.action) {
      case 'upload': {
        if (!input.content || !input.filename) {
          return { error: 'Content and filename required' };
        }
        const file = new File([input.content], input.filename, { 
          type: 'text/plain' 
        });
        const fileId = await CDN.upload(file);
        
        // Store reference
        await Data.create('documents', {
          fileId,
          filename: input.filename,
          uploadedAt: new Date().toISOString()
        });
        
        return { success: true, fileId };
      }
      
      case 'get': {
        if (!input.fileId) {
          return { error: 'File ID required' };
        }
        const file = await CDN.get(input.fileId);
        const content = await file.text();
        return { 
          success: true, 
          filename: file.name,
          content 
        };
      }
      
      case 'analyze': {
        if (!input.fileId) {
          return { error: 'File ID required' };
        }
        const file = await CDN.get(input.fileId);
        const content = await file.text();
        
        const summary = await AI.generate(
          'Summarize this document concisely.',
          [{ type: 'text', text: content }]
        );
        
        return { success: true, summary };
      }
    }
  }
}
If a CDN upload or retrieval isn’t working as expected, log file metadata to inspect what was returned:
const file = await CDN.get(input.fileId);
console.log('CDN file:', file.name, file.type, `${file.size} bytes`);
Then run lua logs --type skill --limit 5 after a test message. See the Debugging Skills guide for the full workflow.