@tapstack/storage

@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