Transactional

Quickstart

Upload and retrieve files — store, download, list, and delete files in agent workspaces.

Install the SDK

npm install @usetransactional/node

Upload a File

import Transactional from '@usetransactional/node';
import { readFileSync } from 'fs';
 
const tx = new Transactional({
  apiKey: process.env.TRANSACTIONAL_API_KEY,
});
 
// Upload a text file
await tx.files.upload({
  workspace: 'my-agent',
  key: 'reports/summary.txt',
  body: 'Monthly revenue: $42,000\nGrowth: 12%',
  contentType: 'text/plain',
});
 
console.log('File uploaded');

Upload Binary Data

// Upload a PDF from disk
const pdfBuffer = readFileSync('/path/to/report.pdf');
 
await tx.files.upload({
  workspace: 'my-agent',
  key: 'reports/q1-report.pdf',
  body: pdfBuffer,
  contentType: 'application/pdf',
  metadata: {
    quarter: 'Q1',
    year: '2026',
    generatedBy: 'analysis-agent',
  },
});

Upload JSON Data

const analysisResult = {
  totalTransactions: 1523,
  averageValue: 47.82,
  topProducts: ['Widget A', 'Widget B'],
};
 
await tx.files.upload({
  workspace: 'my-agent',
  key: 'data/analysis.json',
  body: JSON.stringify(analysisResult),
  contentType: 'application/json',
});

Download a File

const file = await tx.files.download({
  workspace: 'my-agent',
  key: 'reports/summary.txt',
});
 
console.log('Content:', file.body.toString());
console.log('Content-Type:', file.contentType);
console.log('Size:', file.size, 'bytes');
console.log('Last modified:', file.lastModified);

Download with Metadata

const pdf = await tx.files.download({
  workspace: 'my-agent',
  key: 'reports/q1-report.pdf',
});
 
console.log('Metadata:', pdf.metadata);
// { quarter: 'Q1', year: '2026', generatedBy: 'analysis-agent' }

List Files

List all files in a workspace or filter by prefix:

// List all files
const allFiles = await tx.files.list({
  workspace: 'my-agent',
});
 
for (const file of allFiles.items) {
  console.log(`${file.key} (${file.size} bytes)`);
}
 
// List files under a prefix
const reports = await tx.files.list({
  workspace: 'my-agent',
  prefix: 'reports/',
});
 
for (const file of reports.items) {
  console.log(`${file.key} - ${file.lastModified}`);
}

Generate a Presigned URL

Create a time-limited download link to share with users:

const url = await tx.files.getPresignedUrl({
  workspace: 'my-agent',
  key: 'reports/q1-report.pdf',
  expiresIn: 3600, // 1 hour
});
 
console.log('Download link:', url.url);
// Send this URL to a user via email, chat, etc.

Delete a File

await tx.files.delete({
  workspace: 'my-agent',
  key: 'reports/summary.txt',
});
 
console.log('File deleted');

Delete Multiple Files

await tx.files.deleteMany({
  workspace: 'my-agent',
  keys: [
    'data/temp-1.json',
    'data/temp-2.json',
    'data/temp-3.json',
  ],
});

Full Example: Agent with Persistent Storage

import Transactional from '@usetransactional/node';
 
const tx = new Transactional({
  apiKey: process.env.TRANSACTIONAL_API_KEY,
});
 
async function agentWithStorage(taskId: string) {
  const workspace = `task-${taskId}`;
 
  // 1. Check for previous results
  const existing = await tx.files.list({ workspace, prefix: 'results/' });
 
  if (existing.items.length > 0) {
    console.log('Resuming from previous results...');
    const prev = await tx.files.download({
      workspace,
      key: existing.items[0].key,
    });
    console.log('Previous data:', prev.body.toString());
  }
 
  // 2. Run analysis in a sandbox
  const sandbox = await tx.sandboxes.create({ runtime: 'python-3.12' });
  const result = await tx.sandboxes.run(sandbox.id, {
    command: 'python3',
    args: ['-c', 'import json; print(json.dumps({"status": "complete", "score": 94.5}))'],
  });
  await tx.sandboxes.destroy(sandbox.id);
 
  // 3. Store results persistently
  await tx.files.upload({
    workspace,
    key: `results/${new Date().toISOString()}.json`,
    body: result.stdout,
    contentType: 'application/json',
  });
 
  // 4. Generate a shareable link
  const files = await tx.files.list({ workspace, prefix: 'results/' });
  const latest = files.items[files.items.length - 1];
 
  const shareUrl = await tx.files.getPresignedUrl({
    workspace,
    key: latest.key,
    expiresIn: 86400, // 24 hours
  });
 
  return shareUrl.url;
}

Next Steps