import { TuturuuuClient } from 'tuturuuu';

// Initialize the client with your API key
const client = new TuturuuuClient('ttr_your_api_key');

// List files in workspace
const files = await client.storage.list({
  path: 'documents',
  limit: 50
});

// Upload a file
const file = new File(['content'], 'example.txt');
const result = await client.storage.upload(file, {
  path: 'documents'
});

// Create a document
const doc = await client.documents.create({
  name: 'My Document',
  content: { text: 'Hello World' }
});

ttr --help
ttr login
ttr upgrade
ttr --version
ttr whoami
ttr host current
ttr host use local --port 7803
ttr workspaces
ttr workspaces use
ttr boards
ttr boards use
ttr lists use
ttr tasks use
ttr tasks --board <board-id>
ttr tasks --compact
ttr tasks search "deadline review"
ttr tasks search "deadline review" --mode text
ttr tasks search "deadline review" --mode semantic
ttr tasks create "Add Tuturuuu CLI"
ttr tasks create --list <list-id> --name "Write release notes"
ttr tasks done <task-id>
ttr tasks close <task-id>
ttr tasks update <task-id> --json-payload '{"completed":true}'
ttr finance wallets
ttr finance wallets balance --all
ttr finance transactions --page-size 10
ttr finance transactions create --amount 150000 --wallet <wallet-id> --taken-at 2026-05-09
ttr finance transfers migrate --from-transaction <tx-id> --to-transaction <tx-id> --from-wallet <wallet-id> --to-wallet <wallet-id> --amount 150000 --taken-at 2026-05-09
ttr finance budgets status
ttr calendar events list --start 2026-06-11T00:00:00Z --end 2026-06-12T00:00:00Z
ttr calendar events create "Focus block" --start 2026-06-11T09:00:00+07:00 --duration-minutes 90
ttr calendar schedule preview --window-days 14 --timezone Asia/Ho_Chi_Minh

ttr login --copy

ttr box doctor
ttr box setup
ttr box setup --dir .
ttr box repair --dir .
ttr box repair --dir . --dry-run

ttr --help
ttr upgrade --help
ttr box --help
ttr calendar --help
ttr calendar events --help
ttr finance --help
ttr finance transactions --help
ttr tasks --help
ttr tasks search --help
ttr tasks create --help
ttr task-templates --help
ttr task-templates import --help
ttr task-templates export --help
ttr tasks done --help
ttr tasks close --help
ttr tasks update --help
ttr workspaces --help
ttr help tasks create

ttr whoami
ttr whoami --json
ttr workspaces --json --no-update-check
ttr tasks --json --no-update-check

---
key: qa-handoff
name: QA handoff
task_name: Verify release handoff
priority: high
---

| Field | Value |
| --- | --- |
| Owner | Platform |
| Environment | Staging |

# Wallet CRUD.
ttr finance wallets
ttr finance wallets --page 2 --page-size 10
ttr finance wallets get <wallet-id>
ttr finance wallets balance <wallet-id>
ttr finance wallets balance --all
ttr finance wallets create "Cash" --currency VND --balance 0 --type STANDARD
ttr finance wallets update <wallet-id> --name "Operating Cash"
ttr finance wallets delete <wallet-id>

# Transaction CRUD and reporting helpers.
ttr finance transactions --page-size 10
ttr finance transactions --limit 25 --offset 50
ttr finance transactions get <transaction-id>
ttr finance transactions create --amount 150000 --wallet <wallet-id> --taken-at 2026-05-09
ttr finance transactions update <transaction-id> --category <category-id>
ttr finance transactions delete <transaction-id>
ttr finance transactions export --wallets <wallet-id> --start 2026-05-01 --end 2026-05-31
ttr finance transactions stats --start 2026-05-01 --end 2026-05-31

# Transfer creation, update, and id-preserving migration.
ttr finance transfers create --from-wallet <wallet-id> --to-wallet <wallet-id> --amount 150000 --taken-at 2026-05-09
ttr finance transfers update --from-transaction <tx-id> --to-transaction <tx-id> --from-wallet <wallet-id> --to-wallet <wallet-id> --amount 150000 --taken-at 2026-05-09
ttr finance transfers migrate --from-transaction <tx-id> --to-transaction <tx-id> --from-wallet <wallet-id> --to-wallet <wallet-id> --amount 150000 --taken-at 2026-05-09

# Categories, budgets, and recurring transactions.
ttr finance categories create "Travel" --expense --color blue --description "Trips and commuting"
ttr finance budgets create "Marketing" --amount 1000000 --period monthly --start-date 2026-05-01
ttr finance budgets status
ttr finance recurring create "Rent" --amount 5000000 --wallet <wallet-id> --frequency monthly --start-date 2026-05-01
ttr finance recurring upcoming --days-ahead 30

# Event CRUD.
ttr calendar events list --start 2026-06-11T00:00:00Z --end 2026-06-12T00:00:00Z
ttr calendar events get <event-id>
ttr calendar events create "Focus block" --start 2026-06-11T09:00:00+07:00 --duration-minutes 90
ttr calendar events update <event-id> --title "Focus block" --locked true
ttr calendar events delete <event-id>

# Default source and workspace calendar administration.
ttr calendar sources list
ttr calendar sources use --source-provider tuturuuu --calendar <calendar-id>
ttr calendar calendars create "Team" --color BLUE
ttr calendar calendars update <calendar-id> --name "Team Calendar"
ttr calendar calendars reset --yes

# Categories and provider connections.
ttr calendar categories create "Focus" --color BLUE
ttr calendar categories reorder --json-payload '{"categories":[{"id":"...","position":0}]}'
ttr calendar accounts list
ttr calendar auth google
ttr calendar auth microsoft
ttr calendar provider-calendars list --account <account-id>
ttr calendar connections create --calendar-id primary --calendar-name "Primary" --account <account-id>

# Scheduling.
ttr calendar schedule status
ttr calendar schedule tasks --q roadmap
ttr calendar schedule preview --window-days 14 --timezone Asia/Ho_Chi_Minh
ttr calendar schedule apply --mode safe-apply --scope impacted-only --window-days 14 --timezone Asia/Ho_Chi_Minh

# List open tasks in the selected workspace.
ttr tasks

# List active boards only; pass --archived, --deleted, or --all for other states.
ttr boards

# Compact human output: task title, task list, and workspace.
ttr tasks --compact

# Machine-readable output for agents.
ttr tasks --json --no-update-check

# Ranked full-text, semantic, or hybrid search.
ttr tasks search "deadline review"
ttr tasks search "deadline review" --mode hybrid --limit 20 --threshold 0.25
ttr tasks search --query "deadline review" --mode text --json --no-update-check

# Create from the selected board/list, prompting when needed.
ttr tasks create "Add Tuturuuu CLI"

# Create directly into a known list.
ttr tasks create --list <list-id> --name "Write release notes"

# Create and use task templates.
ttr task-templates list
ttr task-templates create "Bug report" --key bug-report --title "Investigate bug" --priority high
ttr task-templates export bug-report --file .tuturuuu/task-templates/bug-report.md
ttr task-templates import .tuturuuu/task-templates/bug-report.md
ttr tiptap parse --text "| Field | Value |\n| --- | --- |\n| Owner | Platform |" --format markdown --output json
ttr tasks create --template bug-report --list <list-id> --name "Investigate checkout bug"
ttr tasks create "QA handoff" --description-file table.md --description-format markdown

# Move with the keyboard picker.
ttr tasks move

# Move directly to a done list.
ttr tasks move VHP-12 --list <done-list-id>

# Quick mark done and use the first done list on the task board when available.
ttr tasks done VHP-12

# Quick mark done with an explicit done destination.
ttr tasks done <task-id> --list <done-list-id>

# Quick mark closed and use the first closed list on the task board when available.
ttr tasks close VHP-12

# Quick mark closed with an explicit closed destination.
ttr tasks close <task-id> --list <closed-list-id>

# Mark completed and let Tuturuuu choose the default done list.
ttr tasks update VHP-12 --json-payload '{"completed":true}'

# Mark completed and choose a specific done destination.
ttr tasks update <task-id> --list <done-list-id> --json-payload '{"completed":true}'

const client = new TuturuuuClient('ttr_your_api_key');

const client = new TuturuuuClient({
  apiKey: 'ttr_your_api_key',
  baseUrl: 'https://tuturuuu.com/api/v1', // optional
  timeout: 30000 // optional, default 30s
});

const files = await client.storage.list({
  path: 'documents', // folder path (optional)
  search: 'report', // search term (optional)
  limit: 50, // max results (optional, default 100)
  offset: 0, // pagination offset (optional)
  sortBy: 'created_at', // sort field (optional)
  sortOrder: 'desc' // sort direction (optional)
});

console.log(files.data); // Array of StorageObject
console.log(files.pagination); // Pagination info

const file = new File(['content'], 'document.pdf');

const result = await client.storage.upload(file, {
  path: 'documents', // destination folder (optional)
  upsert: true // overwrite if exists (optional)
});

console.log(result.data.path); // Relative path
console.log(result.data.fullPath); // Full storage path

const blob = await client.storage.download('documents/report.pdf');

// Save to disk (Node.js)
const buffer = Buffer.from(await blob.arrayBuffer());
await fs.writeFile('report.pdf', buffer);

// Create download link (Browser)
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'report.pdf';
a.click();

const blob = await client.storage.download('images/photo.png', {
  transform: {
    width: 320,
    height: 180,
    resize: 'cover',
    quality: 80
  }
});

const result = await client.storage.delete([
  'documents/old-report.pdf',
  'images/screenshot.png'
]);

console.log(result.data.deleted); // Number of files deleted
console.log(result.data.paths); // Array of deleted paths

const result = await client.storage.createFolder(
  'documents', // parent path
  'reports' // folder name
);

console.log(result.data.path); // "documents/reports"

const result = await client.storage.share('documents/report.pdf', {
  expiresIn: 3600 // 1 hour in seconds (default 3600, max 604800)
});

console.log(result.data.signedUrl); // Temporary URL
console.log(result.data.expiresAt); // ISO timestamp
console.log(result.data.expiresIn); // Seconds until expiration

const result = await client.storage.share('images/photo.png', {
  expiresIn: 3600,
  transform: {
    width: 320,
    height: 180,
    resize: 'contain',
    quality: 85
  }
});

const analytics = await client.storage.getAnalytics();

console.log(analytics.data.totalSize); // Total bytes used
console.log(analytics.data.fileCount); // Number of files
console.log(analytics.data.storageLimit); // Storage limit in bytes
console.log(analytics.data.usagePercentage); // Usage percentage
console.log(analytics.data.largestFile); // Largest file info
console.log(analytics.data.smallestFile); // Smallest file info

const docs = await client.documents.list({
  search: 'meeting', // search in names (optional)
  limit: 20, // max results (optional, default 50)
  offset: 0, // pagination offset (optional)
  isPublic: false // filter by visibility (optional)
});

console.log(docs.data); // Array of Document
console.log(docs.pagination); // Pagination info

const doc = await client.documents.create({
  name: 'Meeting Notes',
  content: {
    text: 'Discussion points...',
    attendees: ['Alice', 'Bob']
  },
  isPublic: false // optional, default false
});

console.log(doc.data.id); // Document ID
console.log(doc.data.name); // Document name
console.log(doc.data.content); // JSONB content

const doc = await client.documents.get('document-id-123');

console.log(doc.data.name);
console.log(doc.data.content);
console.log(doc.data.created_at);

const doc = await client.documents.update('document-id-123', {
  name: 'Updated Meeting Notes', // optional
  content: { text: 'New content' }, // optional
  isPublic: true // optional
});

console.log(doc.data); // Updated document

await client.documents.delete('document-id-123');

const results = await client.documents.search('meeting notes', {
  limit: 10,
  isPublic: false
});

console.log(results.data); // Matching documents

const delivery = await client.externalProjects.getDelivery('workspace-id');

if (delivery.loadingData?.adapter === 'yoola') {
  console.log(delivery.loadingData.featuredArtwork?.title);
  console.log(delivery.loadingData.singletonSections.about?.bodyMarkdown);
}

const yoolaLoadingData =
  await client.externalProjects.getYoolaLoadingData('workspace-id');
console.log(yoolaLoadingData.artworkCategories);

await client.externalProjects.sync.setup('workspace-id', { manifest });

ttr external projects summary --workspace <workspace-id> --json
ttr external projects delivery --workspace <workspace-id> --preview --out tmp/delivery.json
ttr external projects snapshot --workspace <workspace-id> --out tmp/snapshot.json
ttr external projects setup --workspace <workspace-id> --manifest external-project.json
ttr external projects diff --workspace <workspace-id> --manifest external-project.json --json
ttr external projects apply --workspace <workspace-id> --manifest external-project.json --confirm APPLY_EXTERNAL_PROJECT_SYNC

import { linkExternalProjectPublicFolderAssets } from 'tuturuuu';
import { uploadExternalProjectPublicFolderAssets } from 'tuturuuu/external-projects/public-assets';

const linkedManifest = linkExternalProjectPublicFolderAssets(manifest);

const sync = await uploadExternalProjectPublicFolderAssets(
  client.externalProjects,
  'workspace-id',
  manifest,
  { publicDir: './public' }
);

console.log(sync.uploaded.length);
console.log(linkedManifest.content.entries[0]?.assets?.[0]?.storagePath);

import { useQuery } from '@tanstack/react-query';
import {
  getEpmDeliveryQueryOptions,
  getYoolaLoadingDataQueryOptions
} from 'tuturuuu';

const deliveryQuery = useQuery({
  ...getEpmDeliveryQueryOptions(client.externalProjects, 'workspace-id'),
  staleTime: 60_000
});

const yoolaLoadingQuery = useQuery({
  ...getYoolaLoadingDataQueryOptions(client.externalProjects, 'workspace-id'),
  staleTime: 60_000
});

import {
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  ConflictError,
  RateLimitError,
  NetworkError,
  ValidationError
} from 'tuturuuu';

try {
  await client.storage.upload(file);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or expired API key
    console.error('Authentication failed:', error.message);
  } else if (error instanceof AuthorizationError) {
    // Insufficient permissions
    console.error('Forbidden:', error.message);
  } else if (error instanceof NotFoundError) {
    // Resource not found
    console.error('Not found:', error.message);
  } else if (error instanceof ConflictError) {
    // Resource already exists
    console.error('Conflict:', error.message);
  } else if (error instanceof RateLimitError) {
    // Rate limit exceeded
    console.error('Rate limited:', error.message);
  } else if (error instanceof NetworkError) {
    // Network or timeout error
    console.error('Network error:', error.message);
  } else if (error instanceof ValidationError) {
    // Invalid input
    console.error('Validation error:', error.message);
  }
}

try {
  await client.storage.delete([]);
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(error.message); // "At least one path is required"
    console.log(error.code); // "VALIDATION_ERROR"
    console.log(error.statusCode); // 400
    console.log(error.name); // "ValidationError"
  }
}

import type {
  StorageObject,
  Document,
  ListStorageOptions,
  UploadOptions,
  ShareOptions,
  CreateDocumentData,
  UpdateDocumentData,
  ListDocumentsOptions
} from 'tuturuuu';

// Type-safe options
const options: ListStorageOptions = {
  path: 'documents',
  sortBy: 'created_at',
  sortOrder: 'desc'
};

// Type-safe document data
const docData: CreateDocumentData = {
  name: 'My Doc',
  content: { text: 'Content' },
  isPublic: false
};

# .env
TUTURUUU_API_KEY=ttr_your_api_key_here

// app.ts
const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY!);

// BAD: Exposes API key to browser!
'use client'; // Client component

const client = new TuturuuuClient(process.env.NEXT_PUBLIC_API_KEY);
// ❌ Anyone can inspect network requests and steal your key!

// app/api/storage/list/route.ts (SERVER-SIDE)
import { TuturuuuClient } from 'tuturuuu';
import { NextResponse } from 'next/server';

const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY);

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const path = searchParams.get('path') || '';

  const files = await client.storage.list({ path, limit: 50 });
  return NextResponse.json(files);
}

// app/components/FileList.tsx (CLIENT COMPONENT - SAFE)
'use client';

export function FileList() {
  const [files, setFiles] = useState([]);

  useEffect(() => {
    fetch('/api/storage/list?path=documents')
      .then(res => res.json())
      .then(setFiles);
  }, []);

  return <div>{/* Render files */}</div>;
}

// server.js
import { TuturuuuClient } from 'tuturuuu';
import express from 'express';

const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY);
const app = express();

app.get('/api/files', async (req, res) => {
  const files = await client.storage.list();
  res.json(files);
});

app.listen(3000);

// netlify/functions/storage.ts
import { TuturuuuClient } from 'tuturuuu';

export const handler = async (event) => {
  const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY);
  const files = await client.storage.list();

  return {
    statusCode: 200,
    body: JSON.stringify(files)
  };
};

const result = await client.storage.list();

// Access rate limit info from headers (if using direct API calls)
console.log('Limit:', result.headers.get('X-RateLimit-Limit'));
console.log('Remaining:', result.headers.get('X-RateLimit-Remaining'));
console.log(
  'Resets at:',
  new Date(Number.parseInt(result.headers.get('X-RateLimit-Reset')) * 1000)
);

try {
  await client.storage.upload(file);
} catch (error) {
  if (error instanceof RateLimitError) {
    console.error('Rate limited! Try again later.');
    console.error('Retry after:', error.retryAfter, 'seconds');

    // Implement exponential backoff
    await new Promise((resolve) =>
      setTimeout(resolve, error.retryAfter * 1000)
    );
  }
}

RATE_LIMIT_WINDOW_MS = 60000
RATE_LIMIT_MAX_REQUESTS = 500

async function uploadWithRetry(file: File, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.storage.upload(file);
    } catch (error) {
      if (error instanceof RateLimitError && attempt < maxRetries - 1) {
        // Exponential backoff: 1s, 2s, 4s
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}