@jvddavid/cloudflare-images/dist/index.d.cts

Cloudflare Images API wrapper

/**
 * CloudFlare authentication token
 * @typedef {Object} CloudFlareAuthToken
 * @property {string} accountId - The CloudFlare account ID
 * @property {string} token - The CloudFlare account token
 */
interface CloudFlareAuthToken {
    accountId: string;
    token: string;
}
/**
 * CloudFlare authentication key
 * @typedef {Object} CloudFlareAuthKey
 * @property {string} accountId - The CloudFlare account ID
 * @property {string} email - The CloudFlare account email
 * @property {string} key - The CloudFlare account key
 */
interface CloudFlareAuthKey {
    accountId: string;
    email: string;
    key: string;
}
/**
 * CloudFlare authentication
 * @typedef {CloudFlareAuthToken | CloudFlareAuthKey} CloudFlareAuth
 */
type CloudFlareAuth = CloudFlareAuthToken | CloudFlareAuthKey;
/**
 * CloudFlare options
 * @typedef {Object} CloudFlareOptions
 * @property {string} [endpoint] - The CloudFlare API endpoint -> default: 'https://api.cloudflare.com/client/v4'
 */
type CloudFlareOptions = {
    endpoint?: string;
};
/**
 * CloudFlare image options
 * @typedef {Object} ListImagesOptions
 * @property {number} page - The page number
 * @property {number} perPage - The number of images per page
 */
interface ListImagesOptions {
    page: number;
    perPage: number;
}
interface ListImagesV2Options {
    perPage: number;
    sortOrder: 'asc' | 'desc' | null;
    continuationToken: string | null;
}
interface DirectUploadUrlV2Options {
    expiry?: Date;
    metadata?: Record<string, string>;
    requireSignedURLs?: boolean;
}
interface UploadImageOptions {
    name?: string;
    image: Buffer | Blob | string;
    metadata?: Record<string, string>;
    requireSignedURLs?: boolean;
}
interface UploadImageURLOptions {
    imageURL: string;
    metadata?: Record<string, string>;
    requireSignedURLs?: boolean;
}
interface UpdateImageOptions {
    imageId: string;
    metadata?: Record<string, string>;
    requireSignedURLs?: boolean;
}
interface CreateVariantOptions {
    id: string;
    neverRequireSignedURLs?: boolean;
    options: VariantOptions;
}
interface UpdateVariantOptions {
    id: string;
    neverRequireSignedURLs?: boolean;
    options: VariantOptions;
}

interface ListImages {
    images: Image[];
}
interface ListImagesV2 {
    images: Image[];
    continuation_token: string;
}
interface Stats {
    count: {
        allowed: number;
        current: number;
    };
}
interface ImageDetails {
    filename: string;
    id: string;
    meta: Record<string, string>;
    requireSignedURLs: boolean;
    uploaded: string;
    variants: string[];
}
interface DirectUploadUrlV2 {
    id: string;
    uploadURL: string;
}
interface ListSigningKeys {
    keys: {
        name: string;
        value: string;
    }[];
}
interface ListVariants {
    variants: {
        [key: string]: {
            id: string;
            neverRequireSignedURLs: boolean;
            options: VariantOptions;
        };
    };
}
interface VariantDetails {
    variant: {
        id: string;
        neverRequireSignedURLs: boolean;
        options: VariantOptions;
    };
}
interface VariantOptions {
    fit: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad';
    height: number;
    width: number;
    metadata: 'keep' | 'copyright' | 'none';
}
interface UploadImage {
    id: string;
    filename: string;
    meta: Record<string, string>;
    requireSignedURLs: boolean;
    uploaded: string;
    variants: string[];
}
interface Image {
    id: string;
    filename: string;
    meta?: Record<string, string>;
    requireSignedURLs: boolean;
    uploaded: string;
    variants: string[];
}
interface DefaultResponse<Result> {
    success: boolean;
    errors: ErrorCloudFlare[];
    messages: MessagesCloudFlare[];
    result: Result | null;
}
interface ErrorCloudFlare {
    code: number;
    message: string;
}
interface MessagesCloudFlare {
    code: number;
    message: string;
}

declare class CloudFlareImages {
    private readonly auth;
    private readonly baseUrl;
    /**
     * @param {CloudFlareAuth} auth CloudFlareAuth
     * @param {CloudFlareOptions} [options] CloudFlareOptions
     * @example const cloudflare = new CloudFlareImages({ accountId: 'account_id', email: 'email', key: 'key' }, { endpoint: 'https://api.cloudflare.com/client/v4' })
     * @example const cloudflare = new CloudFlareImages({ accountId: 'account_id', token: 'token' }, { endpoint: 'https://api.cloudflare.com/client/v4' })
     * @returns {CloudFlareImages} CloudFlareImages
     */
    constructor(auth: CloudFlareAuth, options?: CloudFlareOptions);
    /**
     * Images v1
     */
    /**
     * list images
     * @param {ListImagesOptions} info list images options
     * @returns object with success, errors, messages and result(images)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.listImages({ page: 1, perPage: 1000 })
     */
    list(info?: ListImagesOptions): Promise<DefaultResponse<ListImages>>;
    /**
     * get stats
     * @returns object with success, errors, messages and result(stats)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.stats()
     */
    stats(): Promise<DefaultResponse<Stats>>;
    /**
     * get image details
     * @param imageId image id
     * @returns object with success, errors, messages and result(image details)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.imageDetails('image_id')
     */
    imageDetails(imageId: string): Promise<DefaultResponse<ImageDetails>>;
    /**
     * get image
     * @param imageId image id
     * @returns object with success, errors, messages and result(base64 image)
     * @throws RequestError
     * @throws Error
     * @example const image = await cloudflare.image('image_id')
     */
    baseImage(imageId: string): Promise<DefaultResponse<string>>;
    /**
     * upload image
     * @param name image name
     * @param image image buffer or base64 string
     * @param metadata image metadata
     * @param requireSignedURLs require signed urls
     * @returns object with success, errors, messages and result(image details)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.uploadImage({ name: 'image_name', image: 'image_base64', metadata: { key: 'value' }, requireSignedURLs: false })
     */
    uploadImage(info: UploadImageOptions): Promise<DefaultResponse<UploadImage>>;
    /**
     * upload image url
     * @param imageURL image url
     * @param metadata image metadata
     * @param requireSignedURLs require signed urls
     * @returns object with success, errors, messages and result(image details)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.uploadImageURL({ imageURL: 'https://example.com/image.png', metadata: { key: 'value' }, requireSignedURLs: false })
     */
    uploadImageURL(info: UploadImageURLOptions): Promise<DefaultResponse<UploadImage>>;
    /**
     * update image
     * @param imageId image id
     * @param metadata image metadata
     * @param requireSignedURLs require signed urls
     * @returns object with success, errors, messages and result(image details)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.updateImage({ imageId: 'image_id', metadata: { key: 'value' }, requireSignedURLs: false })
     */
    updateImage(info: UpdateImageOptions): Promise<DefaultResponse<Image>>;
    /**
     * delete image
     * @param imageId image id
     * @returns object with success, errors, messages and result(empty)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.deleteImage('image_id')
     */
    deleteImage(imageId: string): Promise<DefaultResponse<Record<string, never>>>;
    /**
     * Images v2
     */
    /**
     * list images v2
     * @param perPage number of images per page
     * @param sortOrder sort order
     * @param continuationToken continuation token
     * @returns object with success, errors, messages and result(images, continuation_token)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.listImagesV2({ perPage: 1000, sortOrder: null, continuationToken: null })
     */
    listV2(info?: ListImagesV2Options): Promise<DefaultResponse<ListImagesV2>>;
    /**
     * direct upload url v2
     * @param expiry expiry date (default: 1 hour) '2023-12-13T11:57:06.523Z'
     * @param metadata image metadata
     * @param requireSignedURLs require signed urls
     * @returns object with success, errors, messages and result(direct upload url)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.directUploadUrlV2({ expiry: new Date(Date.now() + 1000 * 60 * 60 * 1), metadata: { key: 'value' }, requireSignedURLs: false })
     */
    directUploadUrlV2(info?: DirectUploadUrlV2Options): Promise<DefaultResponse<DirectUploadUrlV2>>;
    /**
     * Images keys
     */
    /**
     * list signing keys
     * @returns object with success, errors, messages and result(signing keys)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.listSigningKeys()
     */
    listSigningKeys(): Promise<DefaultResponse<ListSigningKeys>>;
    /**
     * Images variants
     */
    /**
     * list variants
     * @returns object with success, errors, messages and result(variants)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.listVariants()
     */
    listVariants(): Promise<DefaultResponse<ListVariants>>;
    /**
     * variant details
     * @param variantId variant id
     * @returns object with success, errors, messages and result(variant details)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.variantDetails('variant_id')
     */
    variantDetails(variantId: string): Promise<DefaultResponse<VariantDetails>>;
    /**
     * create variant
     * @param id variant id
     * @param options variant options
     * @param neverRequireSignedURLs never require signed urls
     * @returns object with success, errors, messages and result(variant details)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.createVariant({ name: 'variant_name', options: { width: 100, height: 100, fit: 'contain', metadata: 'none' } })
     */
    createVariant(info: CreateVariantOptions): Promise<DefaultResponse<VariantDetails>>;
    /**
     * update variant
     * @param id variant id
     * @param options variant options
     * @param neverRequireSignedURLs never require signed urls
     * @returns object with success, errors, messages and result(variant details)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.updateVariant({ id: 'variant_id', options: { width: 100, height: 100, fit: 'contain', metadata: 'none' } })
     */
    updateVariant(info: UpdateVariantOptions): Promise<DefaultResponse<VariantDetails>>;
    /**
     * delete variant
     * @param variantId variant id
     * @returns object with success, errors, messages and result(empty)
     * @throws RequestError
     * @throws Error
     * @example const { success, errors, messages, result } = await cloudflare.deleteVariant('variant_id')
     */
    deleteVariant(variantId: string): Promise<DefaultResponse<Record<string, never>>>;
    /**
     * Private
     */
    private get;
    private post;
    private patch;
    private delete;
    private parseResponse;
    private getHeaders;
    private request;
}

export { CloudFlareImages as default };