shelpin

SDK for Shelpin — pin files to the Shelby network with cryptographic proof.

Install

npm install shelpin

Quick Start

import Shelpin from 'shelpin';

const shelpin = new Shelpin({ apiKey: 'shelpin_your_key_here' });

// Upload a file
const pin = await shelpin.upload(Buffer.from('Hello Shelby!'), 'hello.txt');
console.log(pin.shelbyAddress); // shelby://0x48af.../hello.txt

// Get the public gateway URL
const url = shelpin.gatewayUrl(pin.id, 'hello.txt');
// https://shelpin.forestinfra.com/g/pin_abc123/hello.txt

// List your pins
const { pins } = await shelpin.list();

// Download
const data = await shelpin.download(pin.id);

// Delete
await shelpin.delete(pin.id);

Presigned Uploads (Frontend)

// Server-side: create a token
const token = await shelpin.createUploadToken({
  expiresIn: 300, // 5 minutes
  maxUses: 1,
});

// Client-side: upload with just the token (no API key exposed)
const form = new FormData();
form.append('file', fileInput.files[0]);

await fetch('https://shelpin.forestinfra.com/files/presigned', {
  method: 'POST',
  headers: { 'X-Upload-Token': token.uploadToken },
  body: form,
});

Analytics

const stats = await shelpin.analytics({ days: 7 });
console.log(stats.summary.totalDownloads);
console.log(stats.topFiles);

API

| Method | Description | |---|---| | upload(data, name, metadata?) | Upload a Buffer/Uint8Array | | uploadFromUrl(url, name?) | Fetch and pin from URL | | uploadJson(data, name) | Pin a JSON object | | list(opts?) | List pins with filters | | get(pinId) | Get pin metadata | | download(pinId) | Download file content | | gatewayUrl(pinId, filename?) | Get public gateway URL | | delete(pinId) | Unpin a file | | createUploadToken(opts?) | Create presigned upload token | | analytics(opts?) | Get download analytics | | health() | Check service status |