@deployowl/storage

Zero-config Edge Object Storage SDK for DeployOwl.

Use this SDK to store, stream, serve, and manage files on DeployOwl's global edge infrastructure from Vercel, Render, Cloud Run, Supabase, Railway, Fly.io, or any server environment.

Installation

npm install @deployowl/storage
# or
pnpm add @deployowl/storage
# or
yarn add @deployowl/storage

Quick Start

1. Initialize the client

Construct the client once at module load:

import { createClient } from '@deployowl/storage';

const bucket = createClient({
  apiKey: process.env.OWL_STORAGE_KEY!, // Your owl_ API key (min 32 chars)
  projectId: 'your_project_id',          // Recommended — enables sync CDN URLs
  // gatewayUrl: 'https://owlstorage.deployowl.com', // Optional default
});

Security Note: Your API key is server-only. Never expose it in client-side code or public repositories.

2. Upload a file (put)

// JSON / Text (auto-serialized when passing an object)
await bucket.put('config/settings.json', { theme: 'dark' });
// → { success: true, url: 'https://owlstorage.deployowl.com/cdn/<projectId>/config/settings.json' }

// Binary (ArrayBuffer / Uint8Array / Blob / File / ReadableStream)
await bucket.put('avatars/user_1.jpg', imageBuffer, {
  contentType: 'image/jpeg'
});

Limit: Pre-flight limit of 50 MB per payload for client SDK uploads.

3. Download a file (get)

const file = await bucket.get('avatars/user_1.jpg');
if (!file) return new Response('Not found', { status: 404 });

// file is a StorageResponseWrapper:
//   file.body        → ReadableStream<Uint8Array>
//   file.contentType → 'image/jpeg'
//   file.size        → 204857
//   file.uploadedAt  → ISO Timestamp
//   await file.text() / file.json() / file.arrayBuffer()

return new Response(file.body, {
  headers: { 'Content-Type': file.contentType }
});

4. Synchronous CDN URL (url)

const url = bucket.url('avatars/user_1.jpg');
// → 'https://owlstorage.deployowl.com/cdn/<projectId>/avatars/user_1.jpg'
// Synchronous — zero network call. Perfect for <img src="..."> tags.

5. List and Delete

// List files under a prefix:
const keys = await bucket.list('avatars/');
// → ['avatars/user_1.jpg', 'avatars/user_2.jpg']

// Delete a file:
await bucket.delete('avatars/user_1.jpg');
// → { success: true }

API Reference

| Method | Signature | Description | |---|---|---| | put(key, value, opts?) | key: string, value: object \| string \| ArrayBuffer \| Uint8Array \| Blob \| File \| ReadableStream, opts.contentType?: string | Upload an object. Returns { success, url }. | | get(key) | key: string | Download object. Returns StorageResponseWrapper \| null (404 → null). | | delete(key) | key: string | Delete object. Returns { success: boolean }. | | list(prefix?) | prefix?: string | List object keys by prefix. Returns string[]. | | url(key) | key: string | Get synchronous CDN URL (requires projectId). Returns string. |

Key Naming Rules

• Use / for folder-like paths (e.g. avatars/user_1.jpg).
• Allowed characters: a-z, A-Z, 0-9, -, _, ., /. Max 512 chars.
• . and .. segments are automatically stripped.
• All keys are isolated and scoped strictly to your project.

License

Proprietary © DeployOwl. All rights reserved.