JavaScript SDK

Preview

npm-пакет @fastpic/sdk находится в Preview. Контракт API ниже стабилен, но пакет пока недоступен для публичной установки. Примеры кода демонстрируют запланированный интерфейс.

Установка

После публикации пакета:

terminal

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

Инициализация

Создайте singleton-экземпляр FastPic с вашим API-ключом. Переиспользуйте его по всему приложению.

fastpic-client.ts

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

fp.images.*

Зеркало методов REST API. Те же параметры, те же форматы ответов.

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)

Генерируйте URL трансформаций с помощью fluent-строителя. Ленивый: ничего не выполняется на сервере до вызова 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"

Обработка ошибок

Все выброшенные ошибки — экземпляры FastPicError с полями code, statusCode, requestId и оригинальным сообщением. Используйте switch по полю code для ветвления логики.

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/fastpic не нужен.