@dazl/wix-media-client

Browser client for Wix Media Platform via dazl API server.

Features

• List media files with cursor-based pagination
• File upload with progress tracking and automatic media record creation
• Image URL generation with transformations (fill, fit, crop)
• Direct file URL generation for non-images
• Responsive image set generation
• TypeScript, zero dependencies, browser-safe

Quick Start

All API functions take an endpoint pointing to the media API. The client appends sub-routes internally.

const endpoint = "https://api.dazl.dev/api/media";

List Files

import { listFiles } from "@dazl/wix-media-client";

const result = await listFiles({ endpoint, projectId: "project-uuid" });

// Filter by type
const images = await listFiles({ endpoint, projectId: "project-uuid", mimeType: "image/" });

// Paginate
const page2 = await listFiles({ endpoint, projectId: "project-uuid", cursor: result.nextCursor! });

Upload File

import { uploadFile } from "@dazl/wix-media-client";

const result = await uploadFile({
  endpoint,
  projectId: "project-uuid",
  file: selectedFile,
  onProgress: (progress) => console.log(`${progress.toFixed(0)}%`),
});

The upload flow:

1. POST {endpoint}/upload-configuration — gets a presigned Wix upload URL
2. PUT file directly to Wix CDN (with progress tracking via XHR)
3. POST {endpoint} — creates a media record in the database

Image URLs

import { getFileUrl } from "@dazl/wix-media-client";

const MEDIA_HOST = "wixmp-abc123.appspot.com";

// Image with transforms
const thumbnail = getFileUrl(MEDIA_HOST, { path: "/projects/xxx/photo.jpg", mimeType: "image/jpeg" }, {
  operation: "fill",
  width: 200,
  height: 200,
  quality: 85,
  format: "webp",
});

// Fit within bounds — both `width` and `height` are required by the wixmp
// image service. `fit` preserves aspect ratio so the actual output is bounded
// by whichever axis hits first.
const url = getFileUrl(MEDIA_HOST, { path: "/projects/xxx/photo.jpg", mimeType: "image/jpeg" }, {
  operation: "fit",
  width: 800,
  height: 800,
});

// No transform commands — defaults to fit 1000x1000 (handy for LLM URL fetchers).
const defaultUrl = getFileUrl(MEDIA_HOST, { path: "/projects/xxx/photo.jpg", mimeType: "image/jpeg" });

// Non-image (returns direct URL automatically)
const pdfUrl = getFileUrl(MEDIA_HOST, { path: "/projects/xxx/doc.pdf", mimeType: "application/pdf" });

API Reference

listFiles(options): Promise<ListFilesResponse>

| Option | Type | Default | Description | |---|---|---|---| | endpoint | string | required | Media API endpoint | | projectId | string | required | Project identifier | | mimeType | string | - | Filter by MIME type prefix (e.g., 'image/') | | cursor | string | - | Cursor token for next page | | pageSize | number | 20 | Items per page |

Returns { items: MediaItem[], nextCursor: string | null, total: number }

uploadFile(options): Promise<UploadResult>

| Option | Type | Default | Description | |---|---|---|---| | endpoint | string | required | Media API endpoint | | projectId | string | required | Project identifier | | file | File | required | File to upload | | acl | 'public' \| 'private' | 'public' | Access control | | onProgress | (progress: number) => void | - | Progress callback (0-100) | | createMediaRecord | false | - | Set to false to skip DB record creation |

Returns { success, path, filename, descriptor }

getFileUrl(mediaHost, file, commands?): string

Generate the appropriate URL for a file. Scalable images (PNG, JPEG, GIF, WebP) go through the Wix image service with transforms. Non-scalable images (SVG, ICO) and non-images get a direct URL.

When commands is omitted, raster images get fit 1000×1000 by default (a console.warn is emitted to encourage callers to specify their own). The wixmp image service requires both width and height for fit/fill/crop operations — single-dim transforms return HTTP 400 missing h.

isImageMimeType(mimeType): boolean

createResponsiveImageSet(mediaHost, path, options): Record<number, string>

Each entry in dimensions is generated as fit dimension×dimension (square cap). fit preserves aspect ratio, so the actual output is bounded by whichever axis hits first.

createSrcSet(mediaHost, path, options): string

License

UNLICENSED