📁 RepoHub

A lightweight GitHub content manager for uploading, retrieving, and deleting files from GitHub repositories programmatically.

🔥 Turn any GitHub repository into your personal file server - completely free!

💯 No more costly storage services - leverage GitHub's infrastructure for your file hosting needs

🚀 Simple API to manage your files programmatically - upload, retrieve, and delete with ease

✨ Features

• 🚀 Upload files to GitHub repositories with automatic file naming
• 📥 Retrieve files from repositories with metadata
• 🗑️ Delete files from repositories by name and SHA
• ✅ Built-in validation with Zod
• 📝 TypeScript support
• 🔍 MIME type detection
• 💰 Free file hosting using GitHub's infrastructure
• 🔄 Version control for all your files out of the box

📦 Installation

npm install repohub
# or
yarn add repohub
# or
pnpm add repohub

🔧 Usage

Creating a RepoHub instance

import { createRepHub } from 'repohub';

const repoHub = createRepHub({
  ghToken: 'your-github-personal-access-token',
  ghRepo: 'your-repository-name',
  ghOwner: 'your-github-username'
});

📤 Uploading a file

// Upload a base64-encoded file
const fileData = await repoHub.upload({
  mimeType: 'png', // The file extension without the dot
  content: 'base64EncodedContent==', // Must be valid base64
  path: 'images' // Optional subfolder
});

console.log(fileData);
// {
//   name: 'randomUID.png',
//   path: 'images/randomUID.png',
//   sha: 'file-sha-hash',
//   url: 'github-api-url',
//   download_url: 'raw-file-url'
// }

📋 Getting a file

// Get file metadata by name
const fileData = await repoHub.get({
  name: 'randomUID.png',
  path: 'images' // Optional subfolder
});

console.log(fileData);
// {
//   name: 'randomUID.png',
//   path: 'images/randomUID.png',
//   sha: 'file-sha-hash',
//   url: 'github-api-url',
//   download_url: 'raw-file-url'
// }

🗑️ Deleting a file

// Delete a file (requires its SHA)
const result = await repoHub.delete({
  name: 'randomUID.png',
  path: 'images', // Optional subfolder
  sha: 'file-sha-hash' // Required for deletion
});

console.log(result); // "ok"

💡 Why use GitHub as a file server?

• Completely free - No need to pay for storage services
• Reliable infrastructure - Leverage GitHub's robust platform
• Version control - Every file change is tracked automatically
• Access control - Manage who can access your files using GitHub's permission system
• Public/private options - Choose whether your files are public or private
• No setup required - If you have a GitHub account, you're ready to go

📚 API Reference

createRepHub(options)

Creates a new RepoHub instance.

Parameters

• options (Object): Configuration options
  • ghToken (String): GitHub personal access token
  • ghRepo (String): Repository name
  • ghOwner (String): GitHub username or organization

Returns

An object with the following methods:

• upload({ mimeType, content, path? }): Upload a new file
• get({ name, path? }): Get file metadata
• delete({ name, path?, sha }): Delete a file

⚠️ Handling Errors

All methods throw errors for various failure scenarios:

try {
  await repoHub.upload({ mimeType: 'png', content: 'invalidBase64' });
} catch (error) {
  console.error(error.message);
}

📝 Notes

• Files are named automatically using a randomly generated UID
• Commit messages are also generated randomly
• Content must be base64 encoded before uploading
• You need a GitHub token with appropriate repository permissions
• Respect GitHub's terms of service and storage limitations

🔄 Dependencies

• axios - For HTTP requests
• mrmime - For MIME type detection
• zod - For input validation

📄 License

MIT