object-storage-ovh/README.md

Simple library to use OVH Public Cloud Object Storage.

# ObjectStorage OVH

Simple library to use OVH Public Cloud Object Storage. <br> <br>
Create and manage containers (public, private or static), add and manage objects in OVH Public Cloud (OpenStack).

**Based on** [developer.openstack.org](https://developer.openstack.org/api-ref/object-storage/?expanded=) official documentation.

**Forkde from** [Dimer47](https://github.com/wecrea/node-ovh-objectstorage) ObjectStorage OVh repository.

## 🎉 Features

- Get account details and manage metas (create, update, has, get or delete),
- Create, list, get details or delete containers,
- Check if object exist in a container,
- Define metas (create, update, has, get or delete) for container,
- List files on a container,
- Import object on container
- Download or get content of object,
- Delete all object in containers,
- Program automatic delete of an object on datetime or after seconds,
- Manage metas on objects (create, update, has, get or delete).

## 📍 Install via npm

```sh
npm install object-storage-ovh --save
```

## 🧮 Examples :

### Authentification

Requesting a token to make operations on container.

```javascript
var OVHStorage = require("object-storage-ovh");
var config = {
  username: "******",
  password: "******",
  authURL: "https://auth.cloud.ovh.net/v3/auth",
  tenantId: "******",
  region: "SBG",
};

(async () => {
  try {
    let storage = new OVHStorage(config);
    await storage.connection();
  } catch (e) {
    // throw e
  }
})();
```

### Account

Available methods :

- **all()** _: Object of account details and list containers (Promise)_
- **details()** _: Object (Promise)_
- **containers()** _: Array of each container object (Promise)_
- **metas()**
  - **create(** container, key, value **)** _: Header response (Promise)_
  - **create_with_result(** container, key, value **)** _: Boolean (Promise)_
  - **update(** container, key, value **)** _: Header response (Promise)_
  - **update_with_result(** container, key, value **)** _: Boolean (Promise)_
  - **delete(** container, key **)** _: Header response (Promise)_
  - **delete_with_result(** container, key **)** _: Boolean (Promise)_
  - **all(** container **)** _: Object of metas (Promise)_
  - **has(** container, key **)** _: Boolean (Promise)_
  - **get(** container, key **)** _: String or null (Promise)_

#### Create

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
    try {
        let storage = new OVHStorage(config);
        await storage.connection();

        await storage.containers().create("private-files");
        await storage.containers().create("assets", "static", {
            index:'index.html',
            css: 'style.css',
            error: 'error.html',
        });
        // or with boolean result
        console.log(await storage.containers().create_with_result("images", "public"));
    } catch (e) {
        // throw e
    }
})();
```

#### Delete

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
	try {
		let storage = new OVHStorage(config);
		await storage.connection();

        await storage.containers().delete("assets");
        // or with boolean result
        console.log(await storage.containers().delete_with_result("images"));

	} catch (e) {
        // throw e
	}
})();
```

#### Delete (container and all objects inside)

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
	try {
		let storage = new OVHStorage(config);
		await storage.connection();

        await storage.containers().delete("assets", true);
        // or with boolean result
        console.log(await storage.containers().delete_with_result("images", true));

	} catch (e) {
        // throw e
	}
})();
```

#### Remove all object in container

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
	try {
		let storage = new OVHStorage(config);
		await storage.connection();

        await storage.containers().delete_objects("assets");
        // or with boolean result
        console.log(await storage.containers().delete_objects_with_result("images"));

	} catch (e) {
        // throw e
	}
})();
```

#### List all object in container

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
	try {
		let storage = new OVHStorage(config);
		await storage.connection();

        let objects = await storage.containers().list("assets");
        console.log(objects);
	} catch (e) {
        // throw e
	}
})();

```

#### Check if container exist

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
	try {
		let storage = new OVHStorage(config);
		await storage.connection();

        if(await storage.containers().exist("assets"))
            console.log("Assets container exist !");
	} catch (e) {
        // throw e
	}
})();
```

#### Details about container

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
	try {
		let storage = new OVHStorage(config);
		await storage.connection();

        let details  = await storage.containers().info("assets");
        console.log(details);
	} catch (e) {
        // throw e
	}
})();
```

#### Meta informations of container

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
    try {
        let storage = new OVHStorage(config);
        await storage.connection();

        // list all metas of container
        await storage.containers().metas().all("assets");

        // create a new meta author
        await storage.containers().metas().create("assets", "author", "me");

        // retrieve value of author meta
        console.log(await storage.containers().metas().get("assets", "author"));

        // update value of author meta
        await storage.containers().metas().update("assets", "author", 'unknown');

        // if meta author exist on container name "assets", remove it
        if(await storage.containers().metas().has("assets", "author"))
            await storage.containers().metas().delete("assets", "author");
	} catch (e) {
        // throw e
	}
})();
```

### Containers

Available methods :

- **create(** container, types, web*content_pages **)** *: Header response (Promise)\_
- **create_with_result(** container, types, web*content_pages **)** *: Boolean\_
- **list(** container **)** _: Object (Promise)_
- **exist(** container **)** _: Boolean (Promise)_
- **info(** container **)** _: Header response (Promise)_
- **delete_objects(** container **)** _: Object (Promise)_
- **delete_objects_with_result(** container **)** _: Boolean (Promise)_
- **delete(** container, force=false **)** _: Header response (Promise)_
- **delete_with_result(** container, force=false **)** _: Boolean (Promise)_
- **metas()**
  - **create(** container, key, value **)** _: Header response (Promise)_
  - **create_with_result(** container, key, value **)** _: Boolean (Promise)_
  - **update(** container, key, value **)** _: Header response (Promise)_
  - **update_with_result(** container, key, value **)** _: Boolean (Promise)_
  - **delete(** container, key **)** _: Header response (Promise)_
  - **delete_with_result(** container, key **)** _: Boolean (Promise)_
  - **all(** container **)** _: Object of metas (Promise)_
  - **has(** container, key **)** _: Boolean (Promise)_
  - **get(** container, key **)** _: String or null (Promise)_

#### Create

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
    try {
        let storage = new OVHStorage(config);
        await storage.connection();

        await storage.containers().create("private-files");
        await storage.containers().create("assets", "static", {
            index:'index.html',
            css: 'style.css',
            error: 'error.html',
        });
        // or with boolean result
        console.log(await storage.containers().create_with_result("images", "public"));
    } catch (e) {
        // throw e
    }
})();
```

#### Delete

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
	try {
		let storage = new OVHStorage(config);
		await storage.connection();

        await storage.containers().delete("assets");
        // or with boolean result
        console.log(await storage.containers().delete_with_result("images"));

	} catch (e) {
        // throw e
	}
})();
```

#### Delete (container and all objects inside)

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
	try {
		let storage = new OVHStorage(config);
		await storage.connection();

        await storage.containers().delete("assets", true);
        // or with boolean result
        console.log(await storage.containers().delete_with_result("images", true));

	} catch (e) {
        // throw e
	}
})();
```

#### Remove all object in container

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
	try {
		let storage = new OVHStorage(config);
		await storage.connection();

        await storage.containers().delete_objects("assets");
        // or with boolean result
        console.log(await storage.containers().delete_objects_with_result("images"));

	} catch (e) {
        // throw e
	}
})();
```

#### List all object in container

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
	try {
		let storage = new OVHStorage(config);
		await storage.connection();

        let objects = await storage.containers().list("assets");
        console.log(objects);
	} catch (e) {
        // throw e
	}
})();

```

#### Check if container exist

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
	try {
		let storage = new OVHStorage(config);
		await storage.connection();

        if(await storage.containers().exist("assets"))
            console.log("Assets container exist !");
	} catch (e) {
        // throw e
	}
})();
```

#### Details about container

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
	try {
		let storage = new OVHStorage(config);
		await storage.connection();

        let details  = await storage.containers().info("assets");
        console.log(details);
	} catch (e) {
        // throw e
	}
})();
```

#### Meta informations of container

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
    try {
        let storage = new OVHStorage(config);
        await storage.connection();

        // list all metas of container
        await storage.containers().metas().all("assets");

        // create a new meta author
        await storage.containers().metas().create("assets", "author", "me");

        // retrieve value of author meta
        console.log(await storage.containers().metas().get("assets", "author"));

        // update value of author meta
        await storage.containers().metas().update("assets", "author", 'unknown');

        // if meta author exist on container name "assets", remove it
        if(await storage.containers().metas().has("assets", "author"))
            await storage.containers().metas().delete("assets", "author");
	} catch (e) {
        // throw e
	}
})();
```

### Objects

- **save(** file, path **)** _: Header response (Promise)_
- **save_with_result(** file, path **)** _: Header response (Promise)_
- **set(** file, path **)** _: Header response (Promise)_
- **set_with_result(** file, path **)** _: Header response (Promise)_
- **exist(** path **)** _: Boolean (Promise)_
- **info(** path **)** _: Header response (Promise)_
- **get(** path **)** _: Object with content and header response (Promise)_
- **download(** path, pathLocal **)** _: Boolean (Promise)_
- **copy(** pathOrigin, pathToPaste **)** _: Header response (Promise)_
- **copy_with_result(** **)** _: Boolean (Promise)_
- **delete(** path, checkContainer = true **)** _: Header response (Promise)_
- **delete_with_result(** path, checkContainer = true **)** _: Boolean (Promise)_
- **deletes(** path, checkContainer = true **)** _: Header response of all deleted files (Promise)_
- **deletes_with_result(** path, checkContainer = true **)** _: Boolean (Promise)_
- **expire_at(** path, expire*date **)** *: Header response (Promise)\_
- **expire_at_with_result(** path, expire*date **)** *: Boolean (Promise)\_
- **expire_after(** path, delete*seconds **)** *: Header response (Promise)\_
- **expire_after_with_result(** path, delete*seconds **)** *: Boolean (Promise)\_
- **metas()**
  - **create(** path, key, value **)** _: Header response (Promise)_
  - **create_with_result(** path, key, value **)** _: Boolean (Promise)_
  - **update(** path, key, value **)** _: Header response (Promise)_
  - **update_with_result(** path, key, value **)** _: Boolean (Promise)_
  - **delete(** path, key **)** _: Header response (Promise)_
  - **delete_with_result(** path, key **)** _: Boolean (Promise)_
  - **all(** path **)** _: Object of metas (Promise)_
  - **has(** path, key **)** _: Boolean (Promise)_
  - **get(** path, key **)** _: String or null (Promise)_

#### Download object

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
    try {
        let storage = new OVHStorage(config);
        await storage.connection();

        await storage.objects().download("/assets/IMG_1145.jpg", "./IMG_1145.jpg")
    } catch (e) {
        // throw e
    }
})();
```

#### Get object content

```javascript
(async () => {
  try {
    let storage = new OVHStorage(config);
    await storage.connection();

    let rqt = await storage.objects().get("/assets/IMG_1145.jpg");
    console.log(rqt.content);
  } catch (e) {
    // throw e
  }
})();
```

#### Add object

```javascript
(async () => {
  try {
    let storage = new OVHStorage(config);
    await storage.connection();

    await storage.objects().save("./IMG_1145.jpg", "/assets/IMG_1145.jpg");
    // or with boolean result
    console.log(
      await storage
        .objects()
        .save_with_result("./IMG_1145.jpg", "/assets/IMG_1145.jpg")
    );
  } catch (e) {
    // throw e
  }
})();
```

#### Clone object

```javascript
(async () => {
  try {
    let storage = new OVHStorage(config);
    await storage.connection();

    await storage
      .objects()
      .copy("/assets/IMG_1145.jpg", "/assets/IMG_1145_2.jpg");
    // or with boolean result
    console.log(
      await storage
        .objects()
        .copy_with_result("/assets/IMG_1145.jpg", "/assets/IMG_1145_2.jpg")
    );
  } catch (e) {
    // throw e
  }
})();
```

#### Delete object

```javascript
(async () => {
  try {
    let storage = new OVHStorage(config);
    await storage.connection();

    await storage.objects().delete("/assets/IMG_1145_2.jpg");
    // or with boolean result
    console.log(
      await storage.objects().delete_with_result("/assets/IMG_1145_2.jpg")
    );
  } catch (e) {
    // throw e
  }
})();
```

#### Details about object

```javascript
(async () => {
  try {
    let storage = new OVHStorage(config);
    await storage.connection();

    let details = await storage.objects().info("/assets/IMG_1145.jpg");
    console.log(details);
  } catch (e) {
    // throw e
  }
})();
```

#### Programming object expiration at datetime (need momentjs)

```javascript
(async () => {
  try {
    let storage = new OVHStorage(config);
    await storage.connection();

    await storage
      .objects()
      .expire_at("/assets/IMG_1145.jpg", moment().add("7", "days"));
    // or with boolean result
    console.log(
      await storage
        .objects()
        .expire_at_with_result(
          "/assets/IMG_1145.jpg",
          moment().add("7", "days")
        )
    );
  } catch (e) {
    // throw e
  }
})();
```

#### Programming object expiration after seconds

```javascript
(async () => {
  try {
    let storage = new OVHStorage(config);
    await storage.connection();

    await storage.objects().expire_after("/assets/IMG_1145.jpg", 180);
    // or with boolean result
    console.log(
      await storage
        .objects()
        .expire_after_with_result("/assets/IMG_1145.jpg", 180)
    );
  } catch (e) {
    // throw e
  }
})();
```

#### Meta informations of container

```javascript
var OVHStorage = require('object-storage-ovh');
var config = {
    ...
};

(async () => {
    try {
        let storage = new OVHStorage(config);
        await storage.connection();

        // list all metas of object
        await storage.objects().metas().all("/assets/IMG_1145.jpg");

        // create a new meta author
        await storage.objects().metas().create("/assets/IMG_1145.jpg", "author", "me");

        // retrieve value of author meta
        console.log(await storage.objects().metas().get("/assets/IMG_1145.jpg", "author"));

        // update value of author meta
        await storage.objects().metas().update("/assets/IMG_1145.jpg", "author", 'unknown');

        // if meta author exist on object, remove it
        if(await storage.objects().metas().has("/assets/IMG_1145.jpg", "author"))
            await storage.objects().metas().delete("/assets/IMG_1145.jpg", "author");
	} catch (e) {
        // throw e
	}
})();
```

## 🧾 License

[Creative Commons Attribution Share Alike 4.0 International](LICENSE)