@tapstack/storage

Official Tapstack Storage SDK for file uploads, downloads, image optimization, and folder management.

Installation

npm install @tapstack/storage

Quick Start

Node.js / Server-side

import { TapstackStorage } from '@tapstack/storage';

const storage = new TapstackStorage({
  apiUrl: 'https://api.tapstack.com',
  apiKey: 'ts_...',
});

// Upload a file
const file = await storage.upload(buffer, { name: 'photo.jpg' });

// Get public URL
const url = await storage.getPublicUrl(file.id);

Browser / React

import { TapstackStorage, TapstackStorageProvider, useUpload, useFiles } from '@tapstack/storage';

const storage = new TapstackStorage({
  apiUrl: 'https://api.tapstack.com',
  getToken: () => authClient.getToken(),
});

function App() {
  return (
    <TapstackStorageProvider storage={storage}>
      <FileUploader />
    </TapstackStorageProvider>
  );
}

function FileUploader() {
  const { upload, isUploading, progress } = useUpload();
  const { data } = useFiles({ mimeType: 'image/*' });

  const handleUpload = async (e) => {
    const file = e.target.files[0];
    await upload(file, { tags: ['avatar'] });
  };

  return (
    <div>
      <input type="file" onChange={handleUpload} disabled={isUploading} />
      {isUploading && <p>Uploading: {progress?.percent}%</p>}
      {data?.files.map(f => <img key={f.id} src={f.publicUrl} alt={f.name} />)}
    </div>
  );
}

API Reference

TapstackStorage

Constructor

new TapstackStorage(config: TapstackStorageConfig)

| Option | Type | Description | |--------|------|-------------| | apiUrl | string | Base URL of the Tapstack API (required) | | apiKey | string | API key for server-side calls | | getToken | () => string \| Promise<string> | Dynamic token getter for frontend apps | | userToken | string | Static user token | | workspaceId | string | Workspace ID to scope requests | | placeholderUrl | string | Default placeholder image URL | | fetch | typeof fetch | Custom fetch (for SSR/tests) |

File Methods

| Method | Returns | Description | |--------|---------|-------------| | upload(file, options?) | Promise<StorageFile> | Upload a file | | get(fileId) | Promise<StorageFile> | Get file metadata | | list(options?) | Promise<ListFilesResponse> | List files with filtering | | delete(fileId) | Promise<void> | Delete a file | | getPublicUrl(fileId) | Promise<string> | Get public URL | | getSignedUrl(fileId, options?) | Promise<string> | Get signed download URL | | move(fileId, folderId) | Promise<StorageFile> | Move file to folder | | rename(fileId, newName) | Promise<StorageFile> | Rename a file | | copy(fileId, options?) | Promise<StorageFile> | Copy a file | | search(query, options?) | Promise<ListFilesResponse> | Search files | | addTags(fileId, tags) | Promise<StorageFile> | Add tags | | removeTags(fileId, tags) | Promise<StorageFile> | Remove tags | | getUsage() | Promise<StorageUsage> | Get storage usage/quota |

Folder Methods

| Method | Returns | Description | |--------|---------|-------------| | listFolders(parentId?) | Promise<StorageFolder[]> | List folders | | getFolder(folderId) | Promise<StorageFolder> | Get folder | | createFolder(name, options?) | Promise<StorageFolder> | Create folder | | renameFolder(folderId, name) | Promise<StorageFolder> | Rename folder | | moveFolder(folderId, parentId) | Promise<StorageFolder> | Move folder | | deleteFolder(folderId) | Promise<void> | Delete folder |

Image Methods

| Method | Returns | Description | |--------|---------|-------------| | optimizeImage(file, options?) | Promise<OptimizedImage> | Generate optimized image variants |

React Hooks

| Hook | Returns | Description | |------|---------|-------------| | useUpload(defaults?) | { upload, isUploading, progress, error, data, reset } | File upload with progress | | useFile(fileId) | { data, isLoading, error, refetch } | Fetch file metadata | | useFiles(options?) | { data, isLoading, error, refetch } | Fetch file list | | useFileUrl(fileId, options?) | { url, isLoading, error } | Get file URL | | useImageOptimize() | { optimize, isOptimizing, result, error } | Image optimization | | useFolders(parentId?) | { data, isLoading, error, refetch } | Fetch folder list |

Utilities

| Function | Description | |----------|-------------| | buildSrcSet(variants) | Build an HTML srcSet string from image variants | | generateUniqueFileName(name) | Generate a unique file name with UUID |

Migration from @tapstack/db

The FileModule in @tapstack/db is deprecated. Replace:

- import { createClient } from '@tapstack/db';
- const client = createClient({ ... });
- await client.files.upload(file);
+ import { TapstackStorage } from '@tapstack/storage';
+ const storage = new TapstackStorage({ apiUrl: '...', apiKey: '...' });
+ await storage.upload(file);

License

MIT