architect-node-sdk/README.md

Essentialz Architect Nodejs SDK

# Architect SDK

### Overview

We developed Node.js SDK library in order to make it easier to use Architect services.
The library should spare your time and effort, so you can focus on building great apps and beautiful UIs.
You can read bellow how easy it is to use.

## Getting started

### Installation

Using `npm`

```bash
npm install architect-node-sdk
```

Or using `yarn`

```bash
yarn add architect-node-sdk
```

### Usage

#### JavaScript
```js
import client from 'architect-node-sdk';

const architect = client({
    baseUrl: 'https://example.essentialz.cloud',            // Your project url
    developerKey: 'a36632cc-d6c5-4535-8051-56325bd1ed59',   // Project developer key
});
```
#### Typescript

If you use typescript, you would probably like to define your schema of resources.
This will give you full autocomplete support in your IDE for all resources you define.

```ts
import client, { ArchitectResource } from 'architect-node-sdk';

type ArchitectSchema = {
    cats: ArchitectResource,
    dogs: ArchitectResource,
    birds: ArchitectResource,
}

const architect = client<ArchitectSchema>({
    baseUrl: 'https://example.essentialz.cloud',            // Your project url
    developerKey: 'a36632cc-d6c5-4535-8051-56325bd1ed59',   // Project developer key
});
```

#### Options
When you create architect instance using `architect(config: ArchitectConfig): ArchitectSDK` function you should provide the following configurations:

| Parameter         | Required/Optional | Type      | Default  | Description                                                                                                                          |
|-------------------|-------------------|-----------|----------|--------------------------------------------------------------------------------------------------------------------------------------|
| `baseUrl`         | required          | `string`  |          | Absolute url to your project domain.                                                                                                 |
| `developerKey`    | required          | `string`  |          | Developer key related to your project.                                                                                               |
| `recommendedCase` | optional          | `boolean` | `true`   | Defines whether the SDK will convert names of properties from `camelCase` to `snake_case` before sending and after receiving them.    |

## API reference

### Managing resources

There is no limit how a resource can be named as long the name isn't one of [reserved words](#reserved-names).

You can call it whatever you like and architect SDK will provide you methods for CRUD actions on it.<br/>
We recommend using plural nouns for resource names.

To access these you should simply call `architect.<resource-name>` and it will return you a service with the following methods:

* Fetching all resources:

  `getAll(options?: Options): Promise<ArchitectResource[]>`

  Options:

  | Parameter    | Required/Optional | Type     | Default value | Description                                                                                                          |
    |--------------|-------------------|----------|---------------|----------------------------------------------------------------------------------------------------------------------|
  | `authKey`    | optional          | `string` |               | Auth token of an authenticated project user.                                                                         |
  | `perPage`    | optional          | `number` | `20`          | Number of records that will be returned by API, maximum value is `100`.                                              |
  | `lastReadId` | optional          | `string` |               | Id of last fetched record, used for fetching the next page. If no value is provided API will return first n records. |


* Fetching a single resource:

  `get(resourceId: string, options?: Options): Promise<ArchitectResource>`
* Creating a resource:

  `create(resourceData: Record<String, any>, options?: Options): Promise<ArchitectResource>`
* Updating a resource:

  `update(resourceId: string, resourceData: Record<String, any>, options?: Options): Promise<ArchitectResource>`
* Deleting a resource:

  `delete(resourceId: string, options?: Options): Promise<boolean>`

Currently, `ArchitectResource` is equivalent to `Record<string, any>` but in the future it will contain many useful utilities.

`Options` for all methods except `getAll` is equivalent to `{ authKey?: string }` where `authKey` is auth token of an [authenticated](#Authentication) project user.

#### Example usage

Here is the example how you can manage books resource using SDK.

```js
// This will return all books
const allBooks = await architect.books.getAll();

// This will return single book with id = '5';
const specialBook = await architect.books.get('5');

// Create a new book
const newBook = await architect.books.create({
  name: 'The Adventures of Tom Sawyer',
  author: 'Mark Twain',
});

// Update book with id = '5'
const updatedBook = await architect.books.update('5', {
  numberOfPages: 366
});

// Delete book with id = '5'
await architect.books.delete('5');
```

#### Reserved names

The following words cannot be used as resource name.

* `users` - reserved for project user resource.
* `files` - reserved for the service which is used for managing files.

### Managing files

Architect SDK comes with `files` service for managing files. It contains the following methods:

* Single file upload

  `upload(file: File, options?: Options): Promise<ArchitectFileResource>`

* Bulk upload

  `uploadBulk(files: File[], options?: Options): Promise<ArchitectFileResource[]>`

Currently, `ArchitectFileResource` is equivalent to `{ url: string }`.

`Options` for all methods except `getAll` is equivalent to `{ authKey?: string }` where `authKey` is auth token of an [authenticated](#authentication) project user.

#### Example usage

```js title="Single file upload"
architect.files.upload(file)
  .then((file) => {
      // Manage uploaded file
      // { url: ''}
  })
  .catch((error) => {
      // Handle upload error
  });
```

```js title="Bulk upload"
architect.files.uploadBulk(files)
  .then((files) => {
      // Manage uploaded files
      // [{ url: ''}, { url: ''}, ...]
  })
  .catch((error) => {
      // Handle upload error
  });
```

### Authentication

You can do all the actions on resources and files as an authenticated project user.

All you should do is to simply provide `authKey` that belongs to a project user, as option of resource/file action.

For example:
```js
await architect.books.create({ ...newBookData }, { authKey: 'example-auth-key' });
```