README.md

Azion Storage Client

Azion Storage Client provides a simple interface to interact with the Azion Storage API, allowing you to manage buckets and objects. This client is configurable and supports both debug mode and environment variable-based configuration.

Table of Contents

• Installation
• Environment Variables
• Debug Mode
• Usage
  • Using Environment Variables
  • Direct Method Calls
  • Client Configuration
  • API Examples
    • Create Bucket
    • Delete Bucket
    • Get Buckets
    • Get Bucket by Name
    • Update Bucket
    • Create Object
    • Get Object by Key
    • Get Objects
    • Update Object
    • Delete Object
• API Reference
  • createBucket
  • deleteBucket
  • getBuckets
  • getBucket
  • updateBucket
  • createObject
  • getObjectByKey
  • getObjects
  • updateObject
  • deleteObject
  • createClient
• Types
  • ClientConfig
  • StorageClient
  • AzionStorageResponse
  • Bucket
  • BucketObject
  • DeletedBucket
  • DeletedBucketObject
• Contributing

Installation

Install the package using npm or yarn:

npm install azion

or

yarn add azion

Environment Variables

You can configure the client using the following environment variables:

• AZION_TOKEN: Your Azion API token.
• AZION_DEBUG: Enable debug mode (true/false).

Example .env file:

AZION_TOKEN=your-api-token
AZION_DEBUG=true

Debug Mode

Debug mode provides detailed logging of the API requests and responses. You can enable debug mode by setting the AZION_DEBUG environment variable to true or by passing true as the debug parameter in the methods.

Usage

Using Environment Variables

You can use the environment variables to configure the client without passing the token and debug parameters directly.

Direct Method Calls

You can use the provided wrapper methods to perform storage operations directly.

Client Configuration

You can create a client instance with specific configurations.

API Examples

Create Bucket

JavaScript:

import { createBucket } from '@aziontech/storage';

const { data, error } = await createBucket({ name: 'my-new-bucket', workloads_access: 'read_only' });
if (data) {
  console.log(`Bucket created with name: ${data.name}`);
} else {
  console.error('Failed to create bucket', error);
}

TypeScript:

import { createBucket } from '@aziontech/storage';
import type { AzionStorageResponse, AzionBucket } from '@aziontech/storage';
const { data, error }: AzionStorageResponse<AzionBucket> = await createBucket({
  name: 'my-new-bucket',
  workloads_access: 'read_only',
});
if (data) {
  console.log(`Bucket created with name: ${data.name}`);
} else {
  console.error('Failed to create bucket', error);
}

Delete Bucket

JavaScript:

import { deleteBucket } from '@aziontech/storage';

const { data, error } = await deleteBucket({ name: 'my-bucket' });
if (data) {
  console.log(`Bucket ${data.name} deleted successfully`);
} else {
  console.error('Failed to delete bucket', error);
}

TypeScript:

import { deleteBucket, AzionDeletedBucket, AzionStorageResponse } from '@aziontech/storage';

const { data, error }: AzionStorageResponse<AzionDeletedBucket> = await deleteBucket({ name: 'my-bucket' });
if (data) {
  console.log(`Bucket ${data.name} deleted successfully`);
} else {
  console.error('Failed to delete bucket', error);
}

Get Buckets

JavaScript:

import { getBuckets } from '@aziontech/storage';

const { data: buckets, error } = await getBuckets({ params: { page: 1, page_size: 10 } });
if (buckets) {
  console.log(`Retrieved ${buckets.count} buckets`);
} else {
  console.error('Failed to retrieve buckets', error);
}

TypeScript:

import { getBuckets, AzionStorageResponse, AzionBucketCollection } from '@aziontech/storage';

const { data: buckets, error }: AzionStorageResponse<AzionBucketCollection> = await getBuckets({
  params: { page: 1, page_size: 10 },
});
if (buckets) {
  console.log(`Retrieved ${buckets.count} buckets`);
} else {
  console.error('Failed to retrieve buckets', error);
}

Get Bucket by Name

JavaScript:

import { getBucket } from '@aziontech/storage';

const { data: bucket, error } = await getBucket({ name: 'my-bucket' });
if (bucket) {
  console.log(`Retrieved bucket: ${bucket.name}`);
  console.log(`Workloads access: ${bucket.workloads_access}`);
  console.log(`Last editor: ${bucket.last_editor}`);
  console.log(`Last modified: ${bucket.last_modified}`);
  console.log(`Product version: ${bucket.product_version}`);
} else {
  console.error('Bucket not found', error);
}

TypeScript:

import { getBucket, AzionBucket, AzionStorageResponse } from '@aziontech/storage';

const { data: bucket, error }: AzionStorageResponse<AzionBucket> = await getBucket({ name: 'my-bucket' });
if (bucket) {
  console.log(`Retrieved bucket: ${bucket.name}`);
  console.log(`Workloads access: ${bucket.workloads_access}`);
} else {
  console.error('Bucket not found', error);
}

Setup Storage

The setupStorage function provides a convenient way to ensure a bucket exists. It first tries to get an existing bucket, and if it doesn't exist, creates it automatically. This is perfect for initialization scripts or ensuring your storage is ready to use.

JavaScript:

import { setupStorage } from '@aziontech/storage';

const { data: bucket, error } = await setupStorage({
  name: 'my-app-bucket',
  workloads_access: 'read_write',
});
if (bucket) {
  console.log(`Storage ready: ${bucket.name}`);
  console.log(`Workloads access: ${bucket.workloads_access}`);
} else {
  console.error('Failed to setup storage', error);
}

TypeScript:

import { setupStorage, AzionBucket, AzionStorageResponse } from '@aziontech/storage';

const { data: bucket, error }: AzionStorageResponse<AzionBucket> = await setupStorage({
  name: 'my-app-bucket',
  workloads_access: 'read_write',
});
if (bucket) {
  console.log(`Storage ready: ${bucket.name}`);
  // Now you can safely use the bucket for operations
  await bucket.createObject({
    key: 'config.json',
    content: '{}',
    params: { content_type: 'application/json' },
  });
} else {
  console.error('Failed to setup storage', error);
}

Update Bucket

JavaScript:

import { updateBucket } from '@aziontech/storage';

const { data: updatedBucket, error } = await updateBucket({ name: 'my-bucket', workloads_access: 'private' });
if (updatedBucket) {
  console.log(`Bucket updated: ${updatedBucket.name}`);
} else {
  console.error('Failed to update bucket', error);
}

TypeScript:

import { updateBucket, AzionBucket, AzionStorageResponse } from '@aziontech/storage';

const { data: updatedBucket, error }: AzionStorageResponse<AzionBucket> | null = await updateBucket({
  name: 'my-bucket',
  workloads_access: 'private',
});
if (updatedBucket) {
  console.log(`Bucket updated: ${updatedBucket.name}`);
} else {
  console.error('Failed to update bucket', error);
}

Create Object

JavaScript:

import { createObject } from '@aziontech/storage';

const { data: newObject, error } = await createObject({
  bucket: 'my-bucket',
  key: 'new-file.txt',
  content: 'File 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);
}

TypeScript:

import { createObject, AzionBucketObject, AzionStorageResponse } from '@aziontech/storage';

const { data: newObject, error }: AzionStorageResponse<AzionBucketObject> = await createObject({
  bucket: 'my-bucket',
  key: 'new-file.txt',
  content: 'File 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);
}

Get Object by Key

JavaScript:

import { getObjectByKey } from '@aziontech/storage';

const { data: object, error } = await getObjectByKey({ bucket: 'my-bucket', key: 'file.txt' });
if (object) {
  console.log(`Retrieved object: ${object.key}`);
} else {
  console.error('Object not found', error);
}

TypeScript:

import { getObjectByKey, AzionBucketObject, AzionStorageResponse } from '@aziontech/storage';

const { data: object, error }: AzionStorageResponse<AzionBucketObject> = await getObjectByKey({
  bucket: 'my-bucket',
  key: 'file.txt',
});
if (object) {
  console.log(`Retrieved object: ${object.key}`);
} else {
  console.error('Object not found', error);
}

Get Objects

JavaScript:

import { getObjects } from '@aziontech/storage';

const { data: objectsResult, error } = await getObjects({ bucket: 'my-bucket' });
if (objectsResult) {
  console.log(`Retrieved ${objectsResult.count} objects from the bucket`);
} else {
  console.error('Failed to retrieve objects', error);
}

TypeScript:

import { getObjects, AzionBucketObject, AzionStorageResponse } from '@aziontech/storage';

const { data: objectResult, error }: AzionStorageResponse<AzionBucketObjects> = await getObjects({
  bucket: 'my-bucket',
});
if (objectResult) {
  console.log(`Retrieved ${objectResult.count} objects from the bucket`);
} else {
  console.error('Failed to retrieve objects', error);
}

Update Object

JavaScript:

import { updateObject } from '@aziontech/storage';

const { data: updatedObject, error } = await updateObject({
  bucket: 'my-bucket',
  key: 'file.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);
}

TypeScript:

import { updateObject, AzionBucketObject } from '@aziontech/storage';

const { data: updatedObject, error }: AzionStorageResponse<AzionBucketObject> = await updateObject({
  bucket: 'my-bucket',
  key: 'file.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);
}

Delete Object

JavaScript:

import { deleteObject } from '@aziontech/storage';

const { data: result, error } = await deleteObject({ bucket: 'my-bucket', key: 'file.txt' });
if (result) {
  console.log(`Object ${result.key} deleted successfully`);
} else {
  console.error('Failed to delete object', error);
}

TypeScript:

import { deleteObject, AzionDeletedBucketObject, AzionStorageResponse } from '@aziontech/storage';

const { data: result, error }: AzionStorageResponse<AzionDeletedBucketObject> = await deleteObject({
  bucket: 'my-bucket',
  key: 'file.txt',
});
if (result) {
  console.log(`Object ${result.key} deleted successfully`);
} else {
  console.error('Failed to delete object', error);
}

Using Client

JavaScript:

import { createClient } from '@aziontech/storage';

const client = createClient({ token: 'your-api-token', debug: true });

const { data, error } = await client.createBucket({ name: 'my-new-bucket', workloads_access: 'read_only' });
if (data) {
  console.log(`Bucket created with name: ${data.name}`);
}

const { data: allBuckets } = await client.getBuckets();
if (allBuckets) {
  console.log(`Retrieved ${allBuckets.count} buckets`);
}

// Get a bucket first
const { data: bucket } = await client.getBucket({ name: 'my-new-bucket' });
if (bucket) {
  // Create an object in the bucket
  const { data: newObject } = await bucket.createObject({
    key: 'new-file.txt',
    content: 'File content',
    params: { content_type: 'text/plain' },
  });
  if (newObject) {
    console.log(`Object created with key: ${newObject.key}`);
  }

  // Update the object
  const { data: updateResult } = await bucket.updateObject({
    key: 'new-file.txt',
    content: 'Updated content',
    params: { content_type: 'text/plain' },
  });
  if (updateResult) {
    console.log(`Object updated with key: ${updateResult.key}`);
  }
}

TypeScript:

import {
  createClient,
  StorageClient,
  AzionStorageResponse,
  AzionBucket,
  AzionBucketObject,
  AzionBucketCollection,
} from '@aziontech/storage';

const client: StorageClient = createClient({ token: 'your-api-token', debug: true });

const { data, error }: AzionStorageResponse<AzionBucket> = await client.createBucket({
  name: 'my-new-bucket',
  workloads_access: 'read_only',
});
if (data) {
  console.log(`Bucket created with name: ${data.name}`);
}

const { data: allBuckets }: AzionStorageResponse<AzionBucketCollection> = await client.getBuckets();
if (allBuckets) {
  console.log(`Retrieved ${allBuckets.count} buckets`);
}

// Get a bucket first
const { data: bucket }: AzionStorageResponse<AzionBucket> = await client.getBucket({ name: 'my-new-bucket' });
if (bucket) {
  // Create an object in the bucket
  const { data: newObject }: AzionStorageResponse<AzionBucketObject> = await bucket.createObject({
    key: 'new-file.txt',
    content: 'File content',
    params: { content_type: 'text/plain' },
  });
  if (newObject) {
    console.log(`Object created with key: ${newObject.key}`);
  }

  // Update the object
  const { data: updateResult }: AzionStorageResponse<AzionBucketObject> = await bucket.updateObject({
    key: 'new-file.txt',
    content: 'Updated content',
    params: { content_type: 'text/plain' },
  });
  if (updateResult) {
    console.log(`Object updated with key: ${updateResult.key}`);
  }
}

API Reference

createBucket

Creates a new bucket.

Parameters:

• name: string - Name of the new bucket.
• workloads_access: string - Workloads access configuration for the bucket.
• options?: AzionClientOptions - Optional parameters for the request.

Returns:

• Promise<AzionStorageResponse<AzionBucket>> - The created bucket object or error.

deleteBucket

Deletes a bucket by its name.

Parameters:

• name: string - Name of the bucket to delete.
• debug?: boolean - Enable debug mode for detailed logging.

Returns:

• Promise<AzionStorageResponse<AzionDeletedBucket>> - Object confirming deletion or error.

getBuckets

Retrieves a list of buckets with optional filtering and pagination.

Parameters:

• options?: AzionBucketCollectionOptions - Optional parameters for filtering and pagination.
  • page?: number - Page number for pagination.
  • page_size?: number - Number of items per page.
  • search?: string - Search term to filter buckets by name.
  • ordering?: string - Field name to use when ordering the results.
  • fields?: string - Comma-separated list of field names to include in the response.
• debug?: boolean - Enable debug mode for detailed logging.

Returns:

• Promise<AzionStorageResponse<AzionBucketCollection>> - Array of bucket objects or error.

getBucket

Retrieves a bucket by its name.

Parameters:

• name: string - Name of the bucket to retrieve.
• debug?: boolean - Enable debug mode for detailed logging.

Returns:

• Promise<AzionStorageResponse<AzionBucket>> - The retrieved bucket object or error if not found.

updateBucket

Updates an existing bucket.

Parameters:

• name: string - Name of the bucket to update.
• workloads_access: string - New Workloads access configuration for the bucket.
• debug?: boolean - Enable debug mode for detailed logging.

Returns:

• Promise<AzionStorageResponse<AzionBucket>> - The updated bucket object or error if update failed.

createObject

Creates a new object in a specific bucket.

Parameters:

• bucket: string - Name of the bucket to create the object in.
• key: string - Key (name) of the object to create.
• content: string - Content of the object to upload.
• params?: Object - Object parameters.
• params.content_type?: string - Content type of the object (defaults to 'application/octet-stream').
• options?: AzionClientOptions - Optional parameters including debug mode.

Returns:

• Promise<AzionStorageResponse<AzionBucketObject>> - The created object or error message.

getObjectByKey

Retrieves an object from a specific bucket by its key.

Parameters:

• bucket: string - Name of the bucket containing the object.
• key: string - Key of the object to retrieve.
• options?: AzionClientOptions - Optional parameters including debug mode.

Returns:

• Promise<AzionBucketObject | null> - The retrieved object or null if not found.

getObjects

Retrieves a list of objects in a specific bucket.

Parameters:

• bucket: string - Name of the bucket to retrieve objects from.
• params?: AzionObjectCollectionParams - Optional parameters for object collection.
• options?: AzionClientOptions - Optional parameters including debug mode.

Returns:

• Promise<AzionStorageResponse<AzionBucketObjects>> - Array of bucket objects or error.

updateObject

Updates an existing object in a specific bucket.

Parameters:

• bucket: string - Name of the bucket containing the object.
• key: string - Key of the object to update.
• content: string - New content of the object.
• params?: Object - Object parameters.
• params.content_type?: string - Content type of the object (defaults to 'application/octet-stream').
• options?: AzionClientOptions - Optional parameters including debug mode.

Returns:

• Promise<AzionStorageResponse<AzionBucketObject>> - The updated object or error message.

deleteObject

Deletes an object from a specific bucket.

Parameters:

• bucket: string - Name of the bucket containing the object.
• key: string - Key of the object to delete.
• options?: AzionClientOptions - Optional parameters including debug mode.

Returns:

• Promise<AzionStorageResponse<AzionDeletedBucketObject>> - Confirmation of deletion or error if deletion failed.

createClient

Creates a Storage client with methods to interact with Azion Storage.

Parameters:

• config?: Partial<{ token: string; debug: boolean }> - Configuration options for the Storage client.

Returns:

• StorageClient - An object with methods to interact with Storage.

Types

ClientConfig

Configuration options for the Storage client.

• token?: string - Your Azion API token.
• debug?: boolean - Enable debug mode for detailed logging.

StorageClient

An object with methods to interact with Storage.

• getBuckets: (options?: BucketCollectionOptions) => Promise<AzionStorageResponse<AzionBucketCollection>>
• createBucket: (name: string, workloads_access: string) => Promise<AzionStorageResponse<AzionBucket>>
• updateBucket: (name: string, workloads_access: string) => Promise<AzionStorageResponse<AzionBucket>>
• deleteBucket: (name: string) => Promise<AzionStorageResponse<AzionDeletedBucket>>
• getBucket: (name: string) => Promise<AzionStorageResponse<AzionBucket>>

AzionStorageResponse<T>

The response object from a bucket operation.

• data?: T - The data generic object.
• error?: { message: string; operation: string;}

AzionBucket

The bucket object.

• name: string
• workloads_access?: string
• state?: 'executed' | 'executed-runtime' | 'pending'
• last_editor?: string
• last_modified?: string
• product_version?: string
• getObjects?: (params: { params: AzionObjectCollectionParams }) => Promise<AzionStorageResponse<AzionBucketObjects>>
• getObjectByKey?: (params: { key: string }) => Promise<AzionStorageResponse<AzionBucketObject>>
• createObject?: (params: { key: string, content: string, params?: { content_type?: string } }) => Promise<AzionStorageResponse<AzionBucketObject>>
• updateObject?: (params: { key: string, content: string, params?: { content_type?: string } }) => Promise<AzionStorageResponse<AzionBucketObject>>
• deleteObject?: (params: { key: string }) => Promise<AzionStorageResponse<AzionDeletedBucketObject>>

AzionBucketObject

The bucket object.

• key: string
• state?: 'executed' | 'pending'
• size?: number
• last_modified?: string
• content_type?: string
• content?: string

AzionDeletedBucket

The response object from a delete bucket request.

• name: string
• state: 'executed' | 'pending'

AzionDeletedBucketObject

The response object from a delete object request.

• key: string
• state: 'executed' | 'pending'

Contributing

Feel free to submit issues or pull requests to improve the functionality or documentation.