azion
Version:
Azion Packages for Edge Computing.
667 lines (634 loc) • 27.8 kB
TypeScript
/**
* Represents an Azion storage bucket with methods to interact with objects.
*
* @interface AzionBucket
*
* @property {string} name - The name of the bucket.
* @property {EdgeAccessType} workloads_access - The Workloads access configuration for the bucket.
* @property {'executed' | 'executed-runtime' | 'pending'} [state] - The current state of the bucket.
*/
export declare interface AzionBucket {
name: string;
workloads_access: EdgeAccessType;
state?: 'executed' | 'executed-runtime' | 'pending';
last_editor?: string;
last_modified?: string;
product_version?: string;
/**
* 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 {ContentObjectStorage} params.content - The content of the new object.
* @param {Object} [params.params] - Additional parameters for the object.
* @param {string} [params.params.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!',
* params: { content_type: 'text/plain' }
* });
*/
createObject: (params: {
key: string;
content: ContentObjectStorage;
params?: {
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 {ContentObjectStorage} params.content - The new content for the object.
* @param {Object} [params.params] - Additional parameters for the object.
* @param {string} [params.params.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',
* params: { content_type: 'text/plain' }
* });
*/
updateObject: (params: {
key: string;
content: ContentObjectStorage;
params?: {
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>>;
}
export declare interface AzionBucketCollection {
buckets: AzionBucket[];
count: number;
}
export declare type AzionBucketCollectionParams = {
page?: number;
page_size?: number;
search?: string;
ordering?: string;
fields?: string;
};
export declare interface AzionBucketObject {
key: string;
state?: 'executed' | 'executed-runtime' | 'pending';
size?: number;
last_modified?: string;
content_type?: string;
content?: ContentObjectStorage;
}
export declare interface AzionBucketObjects {
objects: AzionBucketObject[];
count: number;
}
/**
* 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
* };
*/
export declare 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;
};
export declare interface AzionDeletedBucket {
name: string;
state?: 'executed' | 'executed-runtime' | 'pending';
}
export declare interface AzionDeletedBucketObject {
key: string;
state?: 'executed' | 'executed-runtime' | 'pending';
}
/**
* 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
* };
*/
export declare type AzionEnvironment = 'development' | 'staging' | 'production';
export declare type AzionObjectCollectionParams = {
max_object_count?: number;
};
export declare 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.workloads_access - Workloads access configuration for the bucket.
* @returns {Promise<AzionStorageResponse>} The created bucket or error message.
*/
createBucket: (params: {
name: string;
workloads_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.workloads_access - New Workloads access configuration for the bucket.
* @returns {Promise<AzionStorageResponse<AzionBucket>>} The updated bucket or error message.
*/
updateBucket: (params: {
name: string;
workloads_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>>;
/**
* Sets up storage by getting an existing bucket or creating it if it doesn't exist.
* @param {Object} params - Parameters for setting up storage.
* @param {string} params.name - Name of the bucket to setup.
* @param {EdgeAccessType} params.workloads_access - Workloads access configuration for the bucket (used only if creating).
* @returns {Promise<AzionStorageResponse<AzionBucket>>} The existing or created bucket.
*/
setupStorage: (params: {
name: string;
workloads_access: EdgeAccessType;
}) => Promise<AzionStorageResponse<AzionBucket>>;
}
export declare type AzionStorageResponse<T> = {
data?: T;
error?: {
message: string;
operation: string;
};
};
/**
* 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', workloads_access: 'read_only' });
*
* // 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 { client as createClient }
export default client;
export declare type ContentObjectStorage = ArrayBuffer | ReadableStream | Uint8Array | string;
/**
* 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',
* workloads_access: 'read_write'
* });
*/
export declare type CreateAzionStorageClient = (config?: Partial<{
token: string;
options?: AzionClientOptions;
}>) => AzionStorageClient;
/**
* Creates a new bucket.
*
* @param {Object} params - Parameters for creating a bucket.
* @param {string} params.name - Name of the new bucket.
* @param {string} params.workloads_access - Workloads 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', workloads_access: 'read_only', options: { debug: true } });
* if (data) {
* console.log(`Bucket created with name: ${data.name}`);
* } else {
* console.error('Failed to create bucket', error);
* }
*/
export declare const createBucket: ({ name, workloads_access, options, }: {
name: string;
workloads_access: EdgeAccessType;
options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucket>>;
/**
* Creates a new bucket.
*
* @param {string} token - Authentication token for Azion API.
* @param {string} name - Name of the bucket to create.
* @param {string} workloads_access - Workloads access configuration for the bucket.
* @param {AzionClientOptions} [options] - Client options including debug mode.
* @returns {Promise<AzionStorageResponse>} The created bucket object or error message.
*/
export declare const createBucketMethod: (token: string, name: string, workloads_access: EdgeAccessType, options?: AzionClientOptions) => Promise<AzionStorageResponse<AzionBucket>>;
/**
* 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 {Object} [params.params] - Object parameters.
* @param {string} [params.params.content_type] - Content type of the object (defaults to 'application/octet-stream').
* @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',
* params: { content_type: 'text/plain' },
* 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);
* }
*/
export declare const createObject: ({ bucket, key, content, params, options, }: {
bucket: string;
key: string;
content: ContentObjectStorage;
params?: {
content_type?: string;
};
options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucketObject>>;
/**
* 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);
* }
*/
export declare const deleteBucket: ({ name, options, }: {
name: string;
options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionDeletedBucket>>;
/**
* 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.
*/
export declare const deleteBucketMethod: (token: string, name: string, options?: AzionClientOptions) => Promise<AzionStorageResponse<AzionDeletedBucket>>;
/**
* 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);
* }
*/
export declare const deleteObject: ({ bucket, key, options, }: {
bucket: string;
key: string;
options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionDeletedBucketObject>>;
/**
* Workloads 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
*/
export declare type EdgeAccessType = 'read_only' | 'read_write' | 'restricted';
/**
* 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);
* }
*/
export declare const getBucket: ({ name, options, }: {
name: string;
options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucket>>;
/**
* 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);
* }
*/
export declare const getBuckets: ({ params, options, }: {
params?: AzionBucketCollectionParams;
options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucketCollection>>;
/**
* 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.
*/
export declare const getBucketsMethod: (token: string, params?: AzionBucketCollectionParams, options?: AzionClientOptions) => Promise<AzionStorageResponse<AzionBucketCollection>>;
/**
* 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);
* }
*/
export declare const getObjectByKey: ({ bucket, key, options, }: {
bucket: string;
key: string;
options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucketObject>>;
/**
* 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);
* }
*/
export declare const getObjects: ({ bucket, params, options, }: {
bucket: string;
params?: AzionObjectCollectionParams;
options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucketObjects>>;
/**
* Sets up storage by getting an existing bucket or creating it if it doesn't exist.
* This is a convenient wrapper that ensures a bucket exists before use.
*
* @param {Object} params - Parameters for setting up storage.
* @param {string} params.name - Name of the bucket to setup.
* @param {EdgeAccessType} params.workloads_access - Workloads access configuration for the bucket (used only if creating).
* @param {AzionClientOptions} [params.options] - Client options including debug mode.
* @returns {Promise<AzionStorageResponse<AzionBucket>>} The existing or created bucket.
*
* @example
* const { data: bucket, error } = await setupStorage({
* name: 'my-bucket',
* workloads_access: 'read_write',
* options: { debug: true }
* });
* if (bucket) {
* console.log(`Storage ready: ${bucket.name}`);
* } else {
* console.error('Failed to setup storage', error);
* }
*/
export declare const setupStorage: ({ name, workloads_access, options, }: {
name: string;
workloads_access: EdgeAccessType;
options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucket>>;
/**
* Sets up storage by getting an existing bucket or creating it if it doesn't exist.
* This is a convenient wrapper that ensures a bucket exists before use.
*
* @param {string} token - Authentication token for Azion API.
* @param {string} name - Name of the bucket to setup.
* @param {EdgeAccessType} workloads_access - Workloads access configuration for the bucket (used only if creating).
* @param {AzionClientOptions} [options] - Client options including debug mode.
* @returns {Promise<AzionStorageResponse<AzionBucket>>} The existing or created bucket.
*/
export declare const setupStorageMethod: (token: string, name: string, workloads_access: EdgeAccessType, 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.workloads_access - New Workloads 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', workloads_access: 'private', options: { debug: true } });
* if (updatedBucket) {
* console.log(`Bucket updated: ${updatedBucket.name}`);
* } else {
* console.error('Failed to update bucket', error);
* }
*/
export declare const updateBucket: ({ name, workloads_access, options, }: {
name: string;
workloads_access: EdgeAccessType;
options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucket>>;
/**
* Updates an existing bucket.
*
* @param {string} token - Authentication token for Azion API.
* @param {string} name - Name of the bucket to update.
* @param {string} workloads_access - New Workloads access configuration for the bucket.
* @param {AzionClientOptions} [options] - Client options including debug mode.
* @returns {Promise<AzionStorageResponse<AzionBucket>>} The updated bucket or error message.
*/
export declare const updateBucketMethod: (token: string, name: string, workloads_access: EdgeAccessType, options?: AzionClientOptions) => Promise<AzionStorageResponse<AzionBucket>>;
/**
* 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 {Object} [params.params] - Object parameters.
* @param {string} [params.params.content_type] - Content type of the object (defaults to 'application/octet-stream').
* @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',
* params: { content_type: 'text/plain' },
* 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);
* }
*/
export declare const updateObject: ({ bucket, key, content, params, options, }: {
bucket: string;
key: string;
content: ContentObjectStorage;
params?: {
content_type?: string;
};
options?: AzionClientOptions;
}) => Promise<AzionStorageResponse<AzionBucketObject>>;
export { }