Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/buttondown/cli/llms.txt

Use this file to discover all available pages before exploring further.

The images module handles synchronization of media files between Buttondown’s image storage and local filesystem.

​
Overview

Images are fetched from the Buttondown API and stored locally in the media/ directory. The module provides upload functionality for local images to be pushed to Buttondown.

​
Types

​
Image

Based on the Buttondown API Image schema from OpenAPI specification. 
type Image = components["schemas"]["Image"]
Typically includes:
  • id - Unique identifier
  • image - URL to the image file
  • filename - Original filename
  • created - Creation timestamp

​
Functions

​
uploadImage()

Uploads a local image file to Buttondown. 
async function uploadImage(
  configuration: Configuration,
  imagePath: string
): Promise<{ id: string; url: string; filename: string }>
​
configuration
Configuration
required
Configuration object containing API credentials and settings
​
imagePath
string
required
Absolute path to the local image file to upload
​
id
string
Unique identifier for the uploaded image
​
url
string
Public URL where the image is hosted
​
filename
string
Filename of the uploaded image

​
Supported Formats

The function automatically detects MIME types based on file extension:
ExtensionMIME Type
.gifimage/gif
.jpeg, .jpgimage/jpeg
.pngimage/png
.svgimage/svg+xml
.webpimage/webp
Otherapplication/octet-stream

​
Example

import { uploadImage } from "./sync/images.js";

const config = {
  baseUrl: "https://api.buttondown.email/v1",
  apiKey: "your-api-key",
  directory: "./buttondown-data"
};

try {
  const result = await uploadImage(
    config,
    "/path/to/local/logo.png"
  );
  
  console.log(`Uploaded: ${result.filename}`);
  console.log(`URL: ${result.url}`);
  console.log(`ID: ${result.id}`);
} catch (error) {
  console.error("Upload failed:", error.message);
}

​
Error Handling

Throws an error if:
  • The file cannot be read
  • The upload request fails
  • The API returns an error response

​
Resource Objects

​
REMOTE_IMAGES_RESOURCE

Handles image operations with the Buttondown API. 
const REMOTE_IMAGES_RESOURCE: Resource<Image[], Image[]>

​
Methods

get(configuration) Fetches all images from the Buttondown API with automatic pagination. 
async get(configuration: Configuration): Promise<Image[]>
​
configuration
Configuration
required
Configuration with API credentials
​
return
Image[]
Array of all images from the API
  • Fetches images in pages of 100 (defined by PAGE_SIZE)
  • Continues until all pages are retrieved
  • Returns complete array of all images
set(value, configuration) Bulk image upload is not supported via the Buttondown API. 
async set(
  value: Image[],
  configuration: Configuration
): Promise<OperationResult>
Always returns: 
{
  updated: 0,
  created: 0,
  deleted: 0,
  failed: 0
}
Use uploadImage() function for individual uploads instead.

​
LOCAL_IMAGES_RESOURCE

Handles image operations with local filesystem. 
const LOCAL_IMAGES_RESOURCE: Resource<Image[], Buffer[]>

​
Methods

get(configuration) Local image reading is not implemented (returns empty array). 
async get(configuration: Configuration): Promise<Image[]>
​
return
Image[]
Empty array (always returns [])
set(value, configuration) Downloads remote images and saves them to local media/ directory. 
async set(
  value: Image[],
  configuration: Configuration
): Promise<OperationResult>
​
value
Image[]
required
Array of image objects to download
​
configuration
Configuration
required
Configuration with directory path
​
return
OperationResult
Operation result (always returns zeros)

​
Behavior

  • Creates media/ directory if it doesn’t exist
  • Downloads each image from its URL
  • Saves with original filename from URL
  • Overwrites existing files with same name

​
Example

const images = [
  {
    id: "img1",
    image: "https://cdn.buttondown.email/images/abc123.png",
    filename: "logo.png"
  }
];

await LOCAL_IMAGES_RESOURCE.set(images, config);
// Saves to: {directory}/media/abc123.png

​
IMAGES_RESOURCE

Combined resource group for image synchronization. 
const IMAGES_RESOURCE: ResourceGroup<Image[], Image[], Buffer[]>
Provides unified interface for syncing images between remote API and local storage.

​
Properties

​
name
string
Resource identifier: "images"
​
remote
Resource<Image[], Image[]>
Remote API resource handler
​
local
Resource<Image[], Buffer[]>
Local filesystem resource handler

​
Usage Patterns

​
Syncing Images from Remote to Local

import { IMAGES_RESOURCE } from "./sync/images.js";

const config = {
  baseUrl: "https://api.buttondown.email/v1",
  apiKey: "your-api-key",
  directory: "./buttondown-data"
};

// Fetch all remote images
const remoteImages = await IMAGES_RESOURCE.remote.get(config);

console.log(`Found ${remoteImages.length} images`);

// Download to local filesystem
await IMAGES_RESOURCE.local.set(remoteImages, config);

console.log("Images synced to media/ directory");

​
Uploading Local Image

import { uploadImage } from "./sync/images.js";

const uploaded = await uploadImage(
  config,
  "./local-images/new-banner.jpg"
);

console.log(`Image available at: ${uploaded.url}`);

​
Constants

​
EXTENSION_TO_MIME

Mapping of file extensions to MIME types: 
const EXTENSION_TO_MIME: Record<string, string> = {
  ".gif": "image/gif",
  ".jpeg": "image/jpeg",
  ".jpg": "image/jpeg",
  ".png": "image/png",
  ".svg": "image/svg+xml",
  ".webp": "image/webp"
}
Used by uploadImage() to set correct Content-Type header.

Build docs developers (and LLMs) love

Get started for freeTalk to us