PerspectPerspectDocs
Go to Admin
View as Markdown

perspectapi-ts-sdk

Interfaces

  • ImageTransformOptions
  • ResponsiveImageSizes

Variables

  • DEFAULT\_IMAGE\_SIZES

Functions

  • buildImageUrl
  • generateResponsiveImageHtml
  • generateResponsiveUrls
  • generateSizesAttribute
  • generateSrcSet
  • transformMediaItem

Interface: ImageTransformOptions

Cloudflare Image Resizing Integration Transforms images on-the-fly using Cloudflare's Image Resizing service https://developers.cloudflare.com/images/transform-images/transform-via-url/

Properties

background?

optional background?: string

blur?

optional blur?: number

dpr?

optional dpr?: number

fit?

optional fit?: "scale-down" | "contain" | "cover" | "crop" | "pad"

format?

optional format?: "auto" | "avif" | "webp" | "json" | "jpeg" | "png"

gravity?

optional gravity?: "auto" | "left" | "right" | "top" | "bottom" | "center"

height?

optional height?: number

imageUrlPrefix?

optional imageUrlPrefix?: string

URL prefix for image transform paths. Defaults to '/_image'.

metadata?

optional metadata?: "keep" | "copyright" | "none"

quality?

optional quality?: number

rotate?

optional rotate?: 0 | 90 | 180 | 270

sharpen?

optional sharpen?: number

trim?

optional trim?: object

bottom?

optional bottom?: number

left?

optional left?: number

optional right?: number

top?

optional top?: number

width?

optional width?: number

Interface: ResponsiveImageSizes

Properties

large

large: ImageTransformOptions

medium

medium: ImageTransformOptions

original

original: ImageTransformOptions

small

small: ImageTransformOptions

thumbnail

thumbnail: ImageTransformOptions

Function: buildImageUrl()

buildImageUrl(baseUrl, mediaPath, options?): string

Build Cloudflare Image Resizing URL

Parameters

baseUrl

string

The base URL of your API (e.g., "https://api.perspect.comm")

mediaPath

string

The path to the media file (e.g., "media/site/image.jpg")

options?

ImageTransformOptions

Transform options

Returns

string

Cloudflare Image Resizing URL

Example

const url = buildImageUrl(
  'https://api.perspect.comm',
  'media/mysite/photo.jpg',
  { width: 400, format: 'webp', quality: 85 }
);
// Returns: '/cdn-cgi/image/width=400,format=webp,quality=85/https://api.perspect.comm/media/mysite/photo.jpg'

Function: generateResponsiveImageHtml()

generateResponsiveImageHtml(baseUrl, mediaPath, alt, options?): string

Helper to generate complete responsive image HTML

Parameters

baseUrl

string

mediaPath

string

alt

string

options?

className?

string

decoding?

"async" | "sync" | "auto"

loading?

"lazy" | "eager"

sizes?

string

widths?

number[]

Returns

string

Example

const html = generateResponsiveImageHtml(
  'https://api.perspect.comm',
  'media/mysite/photo.jpg',
  'My photo',
  { className: 'rounded-lg', loading: 'lazy' }
);

Function: generateResponsiveUrls()

generateResponsiveUrls(baseUrl, mediaPath, sizes?): Record<keyof ResponsiveImageSizes, string>

Generate responsive image URLs for different sizes

Parameters

baseUrl

string

mediaPath

string

sizes?

ResponsiveImageSizes = DEFAULT_IMAGE_SIZES

Returns

Record<keyof ResponsiveImageSizes, string>

Example

const urls = generateResponsiveUrls(
  'https://api.perspect.comm',
  'media/mysite/photo.jpg'
);
// Returns: { thumbnail: '...', small: '...', medium: '...', large: '...', original: '...' }

Function: generateSizesAttribute()

generateSizesAttribute(breakpoints?): string

Generate sizes attribute for responsive images

Parameters

breakpoints?

object[] = ...

Returns

string

Example

const sizes = generateSizesAttribute();
// Returns: "(max-width: 640px) 100vw, (max-width: 768px) 80vw, ..."

Function: generateSrcSet()

generateSrcSet(baseUrl, mediaPath, widths?): string

Generate srcset for responsive images

Parameters

baseUrl

string

mediaPath

string

widths?

number[] = ...

Returns

string

Example

const srcset = generateSrcSet(
  'https://api.perspect.comm',
  'media/mysite/photo.jpg',
  [400, 800, 1200]
);
// Returns: "...?width=400 400w, ...?width=800 800w, ...?width=1200 1200w"

Function: transformMediaItem()

transformMediaItem(baseUrl, media, sizes?): Record<keyof ResponsiveImageSizes, string>

Transform a MediaItem into responsive URLs Convenience function for working with MediaItem objects from the API

Parameters

baseUrl

string

media

{ link: string; } | { r2_key: string; site_name: string; }

sizes?

ResponsiveImageSizes

Returns

Record<keyof ResponsiveImageSizes, string>

Example

import { transformMediaItem } from 'perspectapi-ts-sdk';

const product = await client.products.getProduct('mysite', 123);
const media = product.data.media?.[0];

if (media) {
  const urls = transformMediaItem('https://api.perspect.comm', media);
  console.log(urls.thumbnail); // Cloudflare-transformed thumbnail URL
}

Variable: DEFAULT_IMAGE_SIZES

const DEFAULT_IMAGE_SIZES: ResponsiveImageSizes

Default responsive image sizes