JavaScript SDK

Preview

The @fastpic/sdk npm package is in preview. The API contract below is stable, but the package is not publicly installable yet. Code samples illustrate the planned shape.

Installation

Once the package is published:

terminal

npm install @fastpic/sdk
# or
yarn add @fastpic/sdk

Initialization

Create a singleton FastPic instance with your API key. Reuse it across your app.

fastpic-client.ts

import { FastPic } from '@fastpic/sdk'
 
export const fp = new FastPic({
  apiKey: process.env.FP_KEY!
})

fp.images.*

Method-mirror of the REST API. Same parameters, same return shapes.

images.ts

// upload
const image = await fp.images.upload(file, { name: 'product.jpg' })
 
// list with pagination
const { items, total } = await fp.images.list({ page: 1, limit: 30 })
 
// retrieve / delete
const one = await fp.images.retrieve(image.publicId)
await fp.images.delete(image.publicId)

fp.url(publicId)

Generate transform URLs with a fluent builder. Lazy: nothing runs server-side until you stringify.

thumb.ts

const src = fp.url(publicId)
  .resize(800, 600)
  .format('webp')
  .quality(85)
  .fit('cover')
  .toString()
// → "https://media.fastpic.pro/{publicId}?w=800&h=600&fmt=webp&q=85&fit=cover"

Error handling

All thrown errors are FastPicError instances with code, statusCode, requestId, and the original message. switch on the code field for branching logic.

catch.ts

try {
  await fp.images.upload(file)
} catch (e) {
  if (e instanceof FastPicError && e.code === 'rate_limit_exceeded') {
    console.warn('backoff: ', e.requestId)
  }
}

TypeScript types

Types ship with the package. No separate @types/fastpic is needed.