azion/packages/storage/README.md

Azion Packages for Edge Computing.

# 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](#installation)
- [Environment Variables](#environment-variables)
- [Debug Mode](#debug-mode)
- [Usage](#usage)
  - [Using Environment Variables](#using-environment-variables)
  - [Direct Method Calls](#direct-method-calls)
  - [Client Configuration](#client-configuration)
  - [API Examples](#api-examples)
    - [Create Bucket](#create-bucket)
    - [Delete Bucket](#delete-bucket)
    - [Get Buckets](#get-buckets)
    - [Get Bucket by Name](#get-bucket-by-name)
    - [Update Bucket](#update-bucket)
    - [Create Object](#create-object)
    - [Get Object by Key](#get-object-by-key)
    - [Get Objects](#get-objects)
    - [Update Object](#update-object)
    - [Delete Object](#delete-object)
- [API Reference](#api-reference)
  - [`createBucket`](#createbucket)
  - [`deleteBucket`](#deletebucket)
  - [`getBuckets`](#getbuckets)
  - [`getBucket`](#getbucket)
  - [`updateBucket`](#updatebucket)
  - [`createObject`](#createobject)
  - [`getObjectByKey`](#getobjectbykey)
  - [`getObjects`](#getobjects)
  - [`updateObject`](#updateobject)
  - [`deleteObject`](#deleteobject)
  - [`createClient`](#createclient)
- [Types](#types)
  - [`ClientConfig`](#clientconfig)
  - [`StorageClient`](#storageclient)
  - [`AzionStorageResponse`](#azionbucketresponse)
  - [`Bucket`](#bucket)
  - [`BucketObject`](#bucketobject)
  - [`DeletedBucket`](#deletedbucket)
  - [`DeletedBucketObject`](#deletedbucketobject)
- [Contributing](#contributing)

## Installation

Install the package using npm or yarn:

```sh
npm install azion
```

or

```sh
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:

```sh
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:**

```javascript
import { createBucket } from 'azion/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:**

```typescript
import { createBucket } from 'azion/storage';
import type { AzionStorageResponse, AzionBucket } from 'azion/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:**

```javascript
import { deleteBucket } from 'azion/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:**

```typescript
import { deleteBucket, AzionDeletedBucket, AzionStorageResponse } from 'azion/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:**

```javascript
import { getBuckets } from 'azion/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:**

```typescript
import { getBuckets, AzionStorageResponse, AzionBucketCollection } from 'azion/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:**

```javascript
import { getBucket } from 'azion/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:**

```typescript
import { getBucket, AzionBucket, AzionStorageResponse } from 'azion/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:**

```javascript
import { setupStorage } from 'azion/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:**

```typescript
import { setupStorage, AzionBucket, AzionStorageResponse } from 'azion/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:**

```javascript
import { updateBucket } from 'azion/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:**

```typescript
import { updateBucket, AzionBucket, AzionStorageResponse } from 'azion/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:**

```javascript
import { createObject } from 'azion/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:**

```typescript
import { createObject, AzionBucketObject, AzionStorageResponse } from 'azion/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:**

```javascript
import { getObjectByKey } from 'azion/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:**

```typescript
import { getObjectByKey, AzionBucketObject, AzionStorageResponse } from 'azion/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:**

```javascript
import { getObjects } from 'azion/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:**

```typescript
import { getObjects, AzionBucketObject, AzionStorageResponse } from 'azion/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:**

```javascript
import { updateObject } from 'azion/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:**

```typescript
import { updateObject, AzionBucketObject } from 'azion/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:**

```javascript
import { deleteObject } from 'azion/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:**

```typescript
import { deleteObject, AzionDeletedBucketObject, AzionStorageResponse } from 'azion/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:**

```javascript
import { createClient } from 'azion/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:**

```typescript
import {
  createClient,
  StorageClient,
  AzionStorageResponse,
  AzionBucket,
  AzionBucketObject,
  AzionBucketCollection,
} from 'azion/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.