npm package: @jmgbb/sdk
Description: Official JavaScript/TypeScript SDK for jmgBB image hosting API
Latest version: 1.0.0

# jmgBB SDK

Official JavaScript/TypeScript SDK for [jmgBB](https://jmgbb.com) image hosting API.

## Install

```bash
npm install jmgbb-sdk
# or
yarn add jmgbb-sdk
# or
pnpm add jmgbb-sdk
```

## Quick Start

```typescript
import { JmgbbClient } from 'jmgbb-sdk'

// Anonymous upload (no account needed)
const client = new JmgbbClient()
const result = await client.upload(fileInput.files[0])
console.log(result.url)  // Direct image URL
console.log(result.urlViewer)  // jmgBB viewer page
```

## Authentication

### JWT Token (logged-in users)

```typescript
const client = new JmgbbClient({
  token: 'your-jwt-token',
})
// All requests will include Authorization: Bearer <token>
```

### API Key (coming soon)

```typescript
const client = new JmgbbClient({
  apiKeyId: 'ak_xxxx',
  apiKeySecret: 'your-secret',
})
```

## Upload

### Single file

```typescript
const result = await client.upload(file, {
  title: 'My Photo',
  description: 'A beautiful sunset',
  expiration: 'P1W',  // 1 week. Options: PT5M, PT15M, PT30M, PT1H, PT3H, PT6H, PT12H, P1D, P2D, P3D, P1W, P1M, P3M, P6M, P1Y
  albumId: 'optional-album-id',
})
```

### Batch upload

```typescript
const results = await client.uploadBatch(files, {
  expiration: 'P1D',
  onProgress: (completed, total) => {
    console.log(`Uploaded ${completed}/${total}`)
  },
})
```

## Images

### List your images

```typescript
const list = await client.listImages({ page: 1, limit: 20 })
console.log(list.items)
console.log(list.total)   // total image count
```

### Get single image

```typescript
const img = await client.getImage('abc123xyz')
console.log(img.url)
```

### Update image

```typescript
await client.updateImage('abc123xyz', {
  title: 'New Title',
  description: 'New description',
  albumId: 'new-album-id-or-null',
})
```

### Delete image

```typescript
// With JWT auth (owner)
await client.deleteImage('abc123xyz')

// Without auth, using delete token from upload result
await client.deleteImage('abc123xyz', deleteToken)
```

## Albums

```typescript
const albums = await client.listAlbums()
```

## Old Photo Restoration

```typescript
// From uploaded file
const result = await client.enhance(fileInput.files[0], "full")
// { id: 'xyz', url: '...', mode: 'full', creditsUsed: 1 }

const result = await client.enhance(fileInput.files[0], "complete")
// Full restoration + colorization + 4x upscale

// From external URL (no upload needed)
const result = await client.enhance("https://example.com/old-photo.jpg", "complete")
```

**Modes:**
- `"light"` — denoise + deblur + 2x upscale
- `"full"` — light + scratch removal + face enhancement + 2x upscale
- `"complete"` — full + colorization + 4x upscale

## Background Removal

```typescript
// Remove background from an uploaded file
const blob = await client.removeBackground(fileInput.files[0])
const url = URL.createObjectURL(blob)
document.querySelector("img").src = url

// Remove background from external URL
const blob = await client.removeBackground("https://example.com/photo.jpg")
```

## Share

```typescript
const share = await client.createShare(['img1-id', 'img2-id'])
console.log(share.url)  // Public gallery URL
```

## Build from source

```bash
npm install
npm run build
```

Outputs `dist/` with CJS and ESM bundles + TypeScript declarations.

## Local Installation (.tgz)

If you want to install from a local `.tgz` package (e.g. for offline or private distribution):

```bash
# Build and package
bash package-local.sh

# Install from local .tgz
npm install ./jmgbb-sdk-<version>.tgz
```

Or distribute the `.tgz` file directly — recipients can install it without npm registry access.

## License

MIT