azion/packages/storage/dist/index.d.mts

Azion Packages for Edge Computing.

/**
 * Edge access configuration for storage buckets.
 *
 * @type {'read_only' | 'read_write' | 'restricted'}
 * @property {'read_only'} read_only - Allows only read operations
 * @property {'read_write'} read_write - Allows both read and write operations
 * @property {'restricted'} restricted - Restricted access with limited permissions
 */
type EdgeAccessType = 'read_only' | 'read_write' | 'restricted';
type AzionStorageResponse<T> = {
    data?: T;
    error?: {
        message: string;
        operation: string;
    };
};
/**
 * Represents an Azion storage bucket with methods to interact with objects.
 *
 * @interface AzionBucket
 *
 * @property {string} name - The name of the bucket.
 * @property {EdgeAccessType} edge_access - The edge access configuration for the bucket.
 * @property {'executed' | 'executed-runtime' | 'pending'} [state] - The current state of the bucket.
 */
interface AzionBucket {
    name: string;
    edge_access: EdgeAccessType;
    state?: 'executed' | 'executed-runtime' | 'pending';
    /**
     * Retrieves a list of objects in the bucket.
     *
     * @param {Object} params - Parameters for retrieving objects.
     * @param {AzionObjectCollectionParams} params.params - Options for filtering and pagination.
     * @returns {Promise<AzionStorageResponse<AzionBucketObjects>>} A promise that resolves to an array of bucket objects or error message.
     *
     * @example
     * const { data: objects, error } = await bucket.getObjects({ params: { max_object_count: 100 } });
     */
    getObjects: (params: {
        params: AzionObjectCollectionParams;
    }) => Promise<AzionStorageResponse<AzionBucketObjects>>;
    /**
     * Retrieves a specific object from the bucket by its key.
     *
     * @param {Object} params - Parameters for retrieving the object.
     * @param {string} params.key - The key of the object to retrieve.
     * @returns {Promise<AzionStorageResponse<AzionBucketObject>>} A promise that resolves to the bucket object or error message.
     *
     * @example
     * const { data: object } = await bucket.getObjectByKey({ key: 'example.txt' });
     */
    getObjectByKey: (params: {
        key: string;
    }) => Promise<AzionStorageResponse<AzionBucketObject>>;
    /**
     * Creates a new object in the bucket.
     *
     * @param {Object} params - Parameters for creating the object.
     * @param {string} params.key - The key for the new object.
     * @param {string} params.content - The content of the new object.
     * @param {Object} [params.options] - Additional options for the object.
     * @param {string} [params.options.content_type] - The content type of the object.
     * @returns {Promise<AzionStorageResponse<AzionBucketObject>>} A promise that resolves to the created bucket object or error message.
     *
     * @example
     * const { data: newObject } = await bucket.createObject({
     *   key: 'new-file.txt',
     *   content: 'Hello, World!',
     *   options: { content_type: 'text/plain' }
     * });
     */
    createObject: (params: {
        key: string;
        content: string;
        options?: {
            content_type?: string;
        };
    }) => Promise<AzionStorageResponse<AzionBucketObject>>;
    /**
     * Updates an existing object in the bucket.
     *
     * @param {Object} params - Parameters for updating the object.
     * @param {string} params.key - The key of the object to update.
     * @param {string} params.content - The new content for the object.
     * @param {Object} [params.options] - Additional options for the object.
     * @param {string} [params.options.content_type] - The new content type for the object.
     * @returns {Promise<AzionStorageResponse<AzionBucketObject>>} A promise that resolves to the updated bucket object or error message.
     *
     * @example
     * const { data: updatedObject } = await bucket.updateObject({
     *   key: 'existing-file.txt',
     *   content: 'Updated content',
     *   options: { content_type: 'text/plain' }
     * });
     */
    updateObject: (params: {
        key: string;
        content: string;
        options?: {
            content_type?: string;
        };
    }) => Promise<AzionStorageResponse<AzionBucketObject>>;
    /**
     * Deletes an object from the bucket.
     *
     * @param {Object} params - Parameters for deleting the object.
     * @param {string} params.key - The key of the object to delete.
     * @returns {Promise<AzionStorageResponse<AzionDeletedBucketObject>>} A promise that resolves to the deleted bucket object or error if deletion failed.
     *
     * @example
     * const { data: deletedObject, error } = await bucket.deleteObject({ key: 'file-to-delete.txt' });
     */
    deleteObject: (params: {
        key: string;
    }) => Promise<AzionStorageResponse<AzionDeletedBucketObject>>;
}
interface AzionBucketObject {
    key: string;
    state?: 'executed' | 'executed-runtime' | 'pending';
    size?: number;
    last_modified?: string;
    content_type?: string;
    content?: string;
}
interface AzionBucketObjects {
    objects: AzionBucketObject[];
    count: number;
}
interface AzionDeletedBucketObject {
    key: string;
    state?: 'executed' | 'executed-runtime' | 'pending';
}
interface AzionDeletedBucket {
    name: string;
    state?: 'executed' | 'executed-runtime' | 'pending';
}
interface AzionBucketCollection {
    buckets: AzionBucket[];
    count: number;
}
interface AzionStorageClient {
    /**
     * Retrieves a list of buckets with optional filtering and pagination.
     * @param {Object} params - Parameters for retrieving buckets.
     * @param {AzionBucketCollectionParams} [params.params] - Optional parameters for filtering and pagination.
     * @returns {Promise<AzionStorageResponse<AzionBucketCollection>>} Array of buckets or error message.
     */
    getBuckets: (params?: {
        params?: AzionBucketCollectionParams;
    }) => Promise<AzionStorageResponse<AzionBucketCollection>>;
    /**
     * Creates a new bucket.
     * @param {Object} params - Parameters for creating a bucket.
     * @param {string} params.name - Name of the new bucket.
     * @param {EdgeAccessType} params.edge_access - Edge access configuration for the bucket.
     * @returns {Promise<AzionStorageResponse>} The created bucket or error message.
     */
    createBucket: (params: {
        name: string;
        edge_access: EdgeAccessType;
    }) => Promise<AzionStorageResponse<AzionBucket>>;
    /**
     * Updates a bucket by its name.
     * @param {Object} params - Parameters for updating a bucket.
     * @param {string} params.name - Name of the bucket to update.
     * @param {EdgeAccessType} params.edge_access - New edge access configuration for the bucket.
     * @returns {Promise<AzionStorageResponse<AzionBucket>>} The updated bucket or error message.
     */
    updateBucket: (params: {
        name: string;
        edge_access: EdgeAccessType;
    }) => Promise<AzionStorageResponse<AzionBucket>>;
    /**
     * Deletes a bucket by its name.
     * @param {Object} params - Parameters for deleting a bucket.
     * @param {string} params.name - Name of the bucket to delete.
     * @returns {Promise<AzionStorageResponse<AzionDeletedBucket>>} Confirmation of deletion or error message.
     */
    deleteBucket: (params: {
        name: string;
    }) => Promise<AzionStorageResponse<AzionDeletedBucket>>;
    /**
     * Retrieves a bucket by its name.
     * @param {Object} params - Parameters for retrieving a bucket.
     * @param {string} params.name - Name of the bucket to retrieve.
     * @returns {Promise<AzionStorageResponse<AzionBucket>>} The retrieved bucket or error message.
     */
    getBucket: (params: {
        name: string;
    }) => Promise<AzionStorageResponse<AzionBucket>>;
}
type AzionBucketCollectionParams = {
    page?: number;
    page_size?: number;
};
type AzionObjectCollectionParams = {
    max_object_count?: number;
};
/**
 * Defines the execution environment for the Azion client.
 *
 * @type {('development' | 'staging' | 'production')}
 *
 * @property {'development'} development - Development environment for local testing
 * @property {'staging'} staging - Staging/testing environment
 * @property {'production'} production - Production environment
 *
 * @example
 * const environment: AzionEnvironment = 'development';
 *
 * @example
 * const clientOptions = {
 *   env: 'production' as AzionEnvironment
 * };
 */
type AzionEnvironment = 'development' | 'staging' | 'production';
/**
 * Options for configuring the Azion client behavior.
 *
 * @property {boolean} [debug] - Enable debug mode for detailed logging.
 * @property {boolean} [force] - Force the operation even if it might be destructive.
 * @property {AzionEnvironment} [env] - Environment to use (dev, stage, prod).
 * @property {boolean} [external] - Force using external REST API instead of built-in runtime API.
 *
 * @example
 * const options: AzionClientOptions = {
 *   debug: true,
 *   force: false,
 *   env: 'dev',
 *   external: false
 * };
 */
type AzionClientOptions = {
    /** Enable debug mode for detailed logging */
    debug?: boolean;
    /** Force the operation even if it might be destructive */
    force?: boolean;
    /** Environment to use (dev, stage, prod) */
    env?: AzionEnvironment;
    /** Force using external REST API instead of built-in runtime API */
    external?: boolean;
};
/**
 * Function type for creating an Azion Storage Client.
 *
 * @param {Object} [config] - Configuration options for the Storage client.
 * @param {string} [config.token] - Authentication token for Azion API. If not provided,
 * the client will attempt to use the AZION_TOKEN environment variable.
 * @param {AzionClientOptions} [config.options] - Additional client options.
 *
 * @returns {AzionStorageClient} An instance of the Azion Storage Client.
 *
 * @example
 * // Create a Storage client with a token and debug mode enabled
 * const storageClient = createAzionStorageClient({
 *   token: 'your-api-token',
 *   options: { debug: true }
 * });
 *
 * @example
 * // Create a Storage client using environment variables for token
 * const storageClient = createAzionStorageClient();
 *
 * @example
 * // Use the Storage client to create a bucket
 * const newBucket = await storageClient.createBucket({
 *   name: 'my-new-bucket',
 *   edge_access: 'read_write'
 * });
 */
type CreateAzionStorageClient = (config?: Partial<{
    token: string;
    options?: AzionClientOptions;
}>) => AzionStorageClient;

/**
 * Creates a new bucket.
 *
 * @param {string} token - Authentication token for Azion API.
 * @param {string} name - Name of the bucket to create.
 * @param {string} edge_access - Edge access configuration for the bucket.
 * @param {AzionClientOptions} [options] - Client options including debug mode.
 * @returns {Promise<AzionStorageResponse>} The created bucket object or error message.
 */
declare const createBucketMethod: (token: string, name: string, edge_access: EdgeAccessType, options?: AzionClientOptions) => Promise<AzionStorageResponse<AzionBucket>>;
/**
 * Deletes a bucket by its name.
 *
 * @param {string} token - Authentication token for Azion API.
 * @param {string} name - Name of the bucket to delete.
 * @param {AzionClientOptions} [options] - Client options including debug mode.
 * @returns {Promise<AzionStorageResponse<AzionDeletedBucket>>} Confirmation of deletion or error message.
 */
declare const deleteBucketMethod: (token: string, name: string, options?: AzionClientOptions) => Promise<AzionStorageResponse<AzionDeletedBucket>>;
/**
 * Retrieves a list of buckets with optional filtering and pagination.
 *
 * @param {string} token - Authentication token for Azion API.
 * @param {AzionBucketCollectionParams} [params] - Optional parameters for filtering and pagination.
 * @param {AzionClientOptions} [options] - Client options including debug mode.
 * @returns {Promise<AzionStorageResponse<AzionBucketCollection>>} Array of bucket objects or error message.
 */
declare const getBucketsMethod: (token: string, params?: AzionBucketCollectionParams, options?: AzionClientOptions) => Promise<AzionStorageResponse<AzionBucketCollection>>;
/**
 * Updates an existing bucket.
 *
 * @param {string} token - Authentication token for Azion API.
 * @param {string} name - Name of the bucket to update.
 * @param {string} edge_access - New edge access configuration for the bucket.
 * @param {AzionClientOptions} [options] - Client options including debug mode.
 * @returns {Promise<AzionStorageResponse<AzionBucket>>} The updated bucket or error message.
 */
declare const updateBucketMethod: (token: string, name: string, edge_access: EdgeAccessType, options?: AzionClientOptions) => Promise<AzionStorageResponse<AzionBucket>>;
/**
 * Creates a new bucket.
 *
 * @param {Object} params - Parameters for creating a bucket.
 * @param {string} params.name - Name of the new bucket.
 * @param {string} params.edge_access - Edge access configuration for the bucket.
 * @param {AzionClientOptions} [params.options] - Client options including debug mode.
 * @returns {Promise<AzionStorageResponse>} The created bucket or error message.
 *
 * @example
 * const { data, error } = await createBucket({ name: 'my-new-bucket', edge_access: 'public', options: { debug: true } });
 * if (data) {
 *   console.log(`Bucket created with name: ${data.name}`);
 * } else {
 *   console.error('Failed to create bucket', error);
 * }
 */
declare const createBucketWrapper: ({ name, edge_access, options, }: {
    name: string;
    edge_access: EdgeAccessType;
    options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucket>>;
/**
 * Deletes a bucket by its name.
 *
 * @param {Object} params - Parameters for deleting a bucket.
 * @param {string} params.name - Name of the bucket to delete.
 * @param {AzionClientOptions} [params.options] - Client options including debug mode.
 * @returns {Promise<AzionStorageResponse<AzionDeletedBucket>>} Confirmation of deletion or error message.
 *
 * @example
 * const { data, error } = await deleteBucket({ name: 'my-bucket', options: { debug: true } });
 * if (data) {
 *   console.log(`Bucket ${data.name} deleted successfully`);
 * } else {
 *   console.error('Failed to delete bucket', error);
 * }
 */
declare const deleteBucketWrapper: ({ name, options, }: {
    name: string;
    options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionDeletedBucket>>;
/**
 * Retrieves a list of buckets with optional filtering and pagination.
 *
 * @param {Object} params - Parameters for retrieving buckets.
 * @param {AzionBucketCollectionParams} [params.params] - Optional parameters for filtering and pagination.
 * @param {AzionClientOptions} [params.options] - Client options including debug mode.
 * @returns {Promise<AzionBucket[] | null>} Array of bucket objects or null if retrieval failed.
 *
 * @example
 * const { data: buckets, error } = await getBuckets({ params: { limit: 10, offset: 0 }, options: { debug: true } });
 * if (buckets) {
 *   console.log(`Retrieved ${buckets.length} buckets`);
 * } else {
 *   console.error('Failed to retrieve buckets', error);
 * }
 */
declare const getBucketsWrapper: ({ params, options, }: {
    params?: AzionBucketCollectionParams;
    options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucketCollection>>;
/**
 * Retrieves a bucket by its name.
 *
 * @param {Object} params - Parameters for retrieving a bucket.
 * @param {string} params.name - Name of the bucket to retrieve.
 * @param {AzionClientOptions} [params.options] - Client options including debug mode.
 * @returns {Promise<AzionStorageResponse<AzionBucket>>} The retrieved bucket or error message.
 *
 * @example
 * const { data: bucket, error } = await getBucket({ name: 'my-bucket', options: { debug: true } });
 * if (bucket) {
 *   console.log(`Retrieved bucket: ${bucket.name}`);
 * } else {
 *   console.error('Bucket not found', error);
 * }
 */
declare const getBucketWrapper: ({ name, options, }: {
    name: string;
    options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucket>>;
/**
 * Updates an existing bucket.
 *
 * @param {Object} params - Parameters for updating a bucket.
 * @param {string} params.name - Name of the bucket to update.
 * @param {string} params.edge_access - New edge access configuration for the bucket.
 * @param {AzionClientOptions} [params.options] - Client options including debug mode.
 * @returns {Promise<AzionStorageResponse<AzionBucket>>} The updated bucket or error message.
 *
 * @example
 * const { data: updatedBucket, error } = await updateBucket({ name: 'my-bucket', edge_access: 'private', options: { debug: true } });
 * if (updatedBucket) {
 *   console.log(`Bucket updated: ${updatedBucket.name}`);
 * } else {
 *   console.error('Failed to update bucket', error);
 * }
 */
declare const updateBucketWrapper: ({ name, edge_access, options, }: {
    name: string;
    edge_access: EdgeAccessType;
    options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucket>>;
/**
 * Retrieves a list of objects in a specific bucket.
 *
 * @param {Object} params - Parameters for retrieving objects.
 * @param {string} params.bucket - Name of the bucket to retrieve objects from.
 * @param {AzionObjectCollectionParams} [params.params] - Optional parameters for object collection.
 * @param {number} [params.params.max_object_count=10000] - Maximum number of objects to retrieve.
 * @param {AzionClientOptions} [params.options] - Client options including debug mode.
 * @returns {Promise<AzionBucketObject[] | null>} Array of bucket objects or null if retrieval failed.
 *
 * @example
 * const { data: objects, error } = await getObjects({ bucket: 'my-bucket', params: { max_object_count: 50 }, options: { debug: true } });
 * if (objects) {
 *   console.log(`Retrieved ${objects.length} objects from the bucket`);
 * } else {
 *   console.error('Failed to retrieve objects', error);
 * }
 */
declare const getObjectsWrapper: ({ bucket, params, options, }: {
    bucket: string;
    params?: AzionObjectCollectionParams;
    options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucketObjects>>;
/**
 * Creates a new object in a specific bucket.
 *
 * @param {Object} params - Parameters for creating an object.
 * @param {string} params.bucket - Name of the bucket to create the object in.
 * @param {string} params.key - Key (name) of the object to create.
 * @param {string} params.content - Content of the content to upload.
 * @param {AzionClientOptions} [params.options] - Client options including debug mode.
 * @returns {Promise<AzionStorageResponse<AzionBucketObject>>} The created object or error message
 *
 * @example
 * const { data: newObject, error } = await createObject({ bucket: 'my-bucket', key: 'new-content.txt', content: 'content content', options: { debug: true } });
 * if (newObject) {
 *   console.log(`Object created with key: ${newObject.key}`);
 *   console.log(`Object content: ${newObject.content}`);
 * } else {
 *   console.error('Failed to create object', error);
 * }
 */
declare const createObjectWrapper: ({ bucket, key, content, options, }: {
    bucket: string;
    key: string;
    content: string;
    options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucketObject>>;
/**
 * Retrieves an object from a specific bucket by its key.
 *
 * @param {Object} params - Parameters for retrieving an object.
 * @param {string} params.bucket - Name of the bucket containing the object.
 * @param {string} params.key - Key of the object to retrieve.
 * @param {AzionClientOptions} [params.options] - Client options including debug mode.
 * @returns {Promise<AzionStorageResponse<AzionBucketObject>>} The retrieved object or error message.
 *
 * @example
 * const { data: object, error } = await getObjectByKey({ bucket: 'my-bucket', key: 'content.txt', options: { debug: true } });
 * if (object) {
 *   console.log(`Retrieved object: ${object.key}`);
 * } else {
 *   console.error('Object not found', error);
 * }
 */
declare const getObjectByKeyWrapper: ({ bucket, key, options, }: {
    bucket: string;
    key: string;
    options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucketObject>>;
/**
 * Updates an existing object in a specific bucket.
 *
 * @param {Object} params - Parameters for updating an object.
 * @param {string} params.bucket - Name of the bucket containing the object.
 * @param {string} params.key - Key of the object to update.
 * @param {string} params.content - New content of the content.
 * @param {AzionClientOptions} [params.options] - Client options including debug mode.
 * @returns {Promise<AzionStorageResponse<AzionBucketObject>>} The updated object or error message.
 *
 * @example
 * const { data: updatedObject, error } = await updateObject({ bucket: 'my-bucket', key: 'content.txt', content: 'Updated content', options: { debug: true } });
 * if (updatedObject) {
 *   console.log(`Object updated: ${updatedObject.key}`);
 *   console.log(`New content: ${updatedObject.content}`);
 * } else {
 *   console.error('Failed to update object', error);
 * }
 */
declare const updateObjectWrapper: ({ bucket, key, content, options, }: {
    bucket: string;
    key: string;
    content: string;
    options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucketObject>>;
/**
 * Deletes an object from a specific bucket.
 *
 * @param {Object} params - Parameters for deleting an object.
 * @param {string} params.bucket - Name of the bucket containing the object.
 * @param {string} params.key - Key of the object to delete.
 * @param {AzionClientOptions} [params.options] - Client options including debug mode.
 * @returns {Promise<AzionStorageResponse<AzionDeletedBucketObject>>} Confirmation of deletion or error if deletion failed.
 *
 * @example
 * const { data: result, error } = await deleteObject({ bucket: 'my-bucket', key: 'content.txt', options: { debug: true } });
 * if (result) {
 *   console.log(`Object ${result.key} deleted successfully`);
 * } else {
 *   console.error('Failed to delete object', error);
 * }
 */
declare const deleteObjectWrapper: ({ bucket, key, options, }: {
    bucket: string;
    key: string;
    options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionDeletedBucketObject>>;
/**
 * Creates a Storage client with methods to interact with Azion Edge Storage.
 *
 * @param {Partial<{ token: string; options?: AzionClientOptions }>} [config] - Configuration options for the Storage client.
 * @returns {AzionStorageClient} An object with methods to interact with Storage.
 *
 * @example
 * const storageClient = createClient({ token: 'your-api-token', options: { debug: true } });
 *
 * // Create a new bucket
 * const { data, error } = await storageClient.createBucket({ name: 'my-new-bucket', edge_access: 'public' });
 *
 * // Get all buckets
 * const { data: allBuckets } = await storageClient.getBuckets({ params: { page: 1, page_size: 10 } });
 *
 * // Delete a bucket
 * const deletedBucket = await storageClient.deleteBucket({ name: 'my-bucket' });
 */
declare const client: CreateAzionStorageClient;

export { type AzionBucket, type AzionBucketCollection, type AzionBucketCollectionParams, type AzionBucketObject, type AzionBucketObjects, type AzionClientOptions, type AzionDeletedBucket, type AzionDeletedBucketObject, type AzionEnvironment, type AzionObjectCollectionParams, type AzionStorageClient, type AzionStorageResponse, type CreateAzionStorageClient, type EdgeAccessType, createBucketWrapper as createBucket, createBucketMethod, client as createClient, createObjectWrapper as createObject, client as default, deleteBucketWrapper as deleteBucket, deleteBucketMethod, deleteObjectWrapper as deleteObject, getBucketWrapper as getBucket, getBucketsWrapper as getBuckets, getBucketsMethod, getObjectByKeyWrapper as getObjectByKey, getObjectsWrapper as getObjects, updateBucketWrapper as updateBucket, updateBucketMethod, updateObjectWrapper as updateObject };