@theloremi/cleepa

React SDK for Cleepa — a standalone digital asset management system on Cloudflare Workers.

Upload, organize, transform, and stream media assets with a simple client API and ready-made React components.

Installation

npm install @theloremi/cleepa

Peer dependencies: react >= 18, react-dom >= 18

Quick Start

import { Cleepa } from '@theloremi/cleepa'

const cleepa = new Cleepa({
  baseUrl: 'https://your-cleepa-worker.workers.dev',
  getToken: async () => {
    // Return your Supabase access token
    const { data } = await supabase.auth.getSession()
    return data.session?.access_token ?? null
  },
})

// Upload an image
const asset = await cleepa.upload(file, { title: 'Hero Image', type: 'image' })

// Get a resized thumbnail URL (public, no auth needed)
const thumb = cleepa.getImageUrl(asset.id, { w: 300, h: 200, format: 'webp' })

// Organize into folders
const folder = await cleepa.createFolder('Marketing')
await cleepa.moveAssetToFolder(asset.id, folder.id)

// Stream video
const streamUrl = cleepa.getStreamUrl(videoAssetId)

API Client

Constructor

const cleepa = new Cleepa({
  baseUrl: string,                          // Your Cleepa worker URL
  getToken?: () => Promise<string | null>,  // Auth token provider
})

Asset Methods

| Method | Description | |--------|-------------| | upload(file, options) | Upload a file. Options: { title, type } | | list(options?) | List assets. Options: { type?, folderId? } | | get(assetId) | Get a single asset by ID | | delete(assetId) | Delete an asset and its R2 files | | moveAssetToFolder(assetId, folderId) | Move asset to folder (or null for root) |

Image Methods

| Method | Description | |--------|-------------| | getImageUrl(assetId, options?) | Build a transform URL. Options: { w?, h?, fit?, format?, quality? } |

Transform options:

• w / h — target dimensions (max 4096px)
• fit — cover, contain, crop, or scale-down
• format — webp, avif, jpeg, png, or auto
• quality — 1-100 (default: 80)

Video Methods

| Method | Description | |--------|-------------| | getStreamUrl(assetId) | Get HLS stream URL for a video asset |

Folder Methods

| Method | Description | |--------|-------------| | createFolder(name, parentId?) | Create a folder (nested if parentId provided) | | listFolders(parentId?) | List folders, optionally filtered by parent | | renameFolder(folderId, name) | Rename a folder | | deleteFolder(folderId, force?) | Delete folder. force: true moves contents to root |

React Components

Player

HLS video player with HLS.js. Falls back to native HLS on Safari.

import { Player } from '@theloremi/cleepa'

<Player
  assetId="abc123"
  baseUrl="https://your-cleepa-worker.workers.dev"
  autoPlay={false}
  className="my-player"
/>

| Prop | Type | Required | Default | |------|------|----------|---------| | assetId | string | Yes | — | | baseUrl | string | Yes | — | | autoPlay | boolean | No | false | | className | string | No | — |

MediaPicker

Grid UI for browsing and selecting assets.

import { MediaPicker } from '@theloremi/cleepa'

<MediaPicker
  baseUrl="https://your-cleepa-worker.workers.dev"
  getToken={getToken}
  onSelect={(asset) => console.log(asset)}
  type="image"
/>

| Prop | Type | Required | Default | |------|------|----------|---------| | baseUrl | string | Yes | — | | getToken | () => Promise<string \| null> | Yes | — | | onSelect | (asset: Asset) => void | Yes | — | | type | 'video' \| 'image' \| 'audio' \| 'document' | No | all | | className | string | No | — |

Types

import type { Asset, Folder, CleepaConfig, UploadOptions, PlayerProps, MediaPickerProps } from '@theloremi/cleepa'

interface Asset {
  id: string
  title: string
  filename: string
  mimeType: string
  sizeBytes: number
  r2Key: string
  type: 'video' | 'image' | 'audio' | 'document'
  status: 'uploading' | 'encoding' | 'ready' | 'failed'
  variants?: string[]
  metadata?: Record<string, unknown>
  folderId?: string
  uploadedAt: string
  streamUrl?: string
}

interface Folder {
  id: string
  name: string
  parentId: string | null
  depth: number
  createdAt: string
}

interface UploadOptions {
  title: string
  type: 'video' | 'image' | 'audio' | 'document'
}

Requirements

• A deployed Cleepa worker (see main repo)
• Supabase project for authentication
• React 18+

License

MIT