MonkeyBuckets

S3-backed file storage with a key-value API. Public files get permanent CDN URLs. Private files get time-limited signed URLs. File bytes never pass through MonkeyHub servers.

Bucket Creation

typescript

const bucket = db.bucket('uploads')

Upload Files

Upload a file with a visibility setting. Public files are served via CloudFront CDN. Private files require signed URLs.

typescript

// Public file — gets a permanent CDN URL
await bucket.put('logo.png', file, { visibility: 'public' })

// Private file — accessed via signed URLs
await bucket.put('tax-return.pdf', file, { visibility: 'private' })

// With custom metadata
await bucket.put('report.pdf', file, {
  visibility: 'private',
  contentType: 'application/pdf',
  metadata: { department: 'finance', quarter: 'Q4' },
})

Note: Uploads use S3 pre-signed URLs — file bytes go directly to S3, not through MonkeyHub servers. This supports files up to your plan's max file size.

Get File URLs

typescript

// Public file — permanent CDN URL
const cdnUrl = await bucket.getUrl('logo.png')
// → "https://cdn.monkeyhub.io/org_abc/uploads/logo.png"

// Private file — signed URL (default 15 min expiry)
const signedUrl = await bucket.getUrl('tax-return.pdf')
// → "https://s3.amazonaws.com/...?X-Amz-Signature=..."

// Private file — custom expiry
const longUrl = await bucket.getUrl('tax-return.pdf', { expiresIn: 3600 })
// → signed URL valid for 1 hour

File Metadata

typescript

const meta = await bucket.getMeta('logo.png')
// {
//   filename: 'logo.png',
//   visibility: 'public',
//   size: 24576,
//   contentType: 'image/png',
//   metadata: {},
//   url: 'https://cdn.monkeyhub.io/...',
//   createdAt: '2025-01-15T10:00:00Z',
// }

Query Files

List files in a bucket, optionally filtering by file extension.

typescript

// List all files
const all = await bucket.query({})

// Filter by extension
const images = await bucket.query({ ext: 'png' })

// Paginate
const page = await bucket.query({ limit: 20, cursor: previousCursor })

Delete Files

Removes the file from S3 and deletes its metadata record.

typescript

await bucket.remove('old-file.png')

Limits

	Baby Monkey	Chimp	Mandrill	Silverback
Max file size	50 MB	250 MB	500 MB	5 GB
Max files / bucket	1,000	10,000	100,000	Unlimited
Total storage	500 MB	5 GB	25 GB	500 GB
Uploads / min	10	25	100	1,000