@awhere/api/README.md

The awesome aWhere API for JavaScript.

# @awhere/api

# 1. Register the API with your credentials

## - Register with API Key

```js
import { APIKey, CredentialType, identityManager } from '@awhere/api/identity';
const credential = new APIKey({
    aWhereUrl: '<Your aWhere URL>',
    key: '<Your aWhere API Key>',
});
identityManager.registers([credential]);
identityManager.setDefaultCredential(credential);
```

## - Register with OAuth2.0 flow

### ES6

```js
// signin.js

import { OAuth, CredentialType, identityManager } from '@awhere/api/identity';
const credential = new OAuth({
    aWhereUrl: '<Your aWhere URL>',
    appId: '<Your App Id>',
    callbackUrl: '/oauth-callback',
});
identityManager.registers([credential]);
identityManager.setDefaultCredential(credential);
credential.syncWithStorage().then(() => {
    if (!identityManager.defaultOAuth.signedIn) {
        return identityManager.defaultOAuth.signIn();
    }
    // go to the signed-in page
});
```

```js
// oauth-callback.js

import { fetchToken } from '@awhere/api/identity';

fetchToken(location)
    .then(() => {
        // authorized page
        location.href = '/';
    })
    .catch((err) => {
        // oauth flow authorized page
        location.href = '/sigin?' + err;
    });
```

### HTML

```html
<script src="<Your aWhere JavaScript API URL>"></script>
<script>
    const credential = new awhere.identity.OAuth({
        aWhereUrl: '<Your aWhere URL>',
        appId: '<Your App Id>',
        callbackUrl: '/oauth-callback.html',
    });
    awhere.identity.identityManager.registers([credential]);
    awhere.identity.identityManager.setDefaultCredential(credential);
    credential.syncWithStorage().then(() => {
        if (!awhere.identity.identityManager.defaultOAuth.signedIn) {
            return awhere.identity.identityManager.defaultOAuth.signIn();
        }
        // go to the signed-in page
    });
</script>
```

```html
<!-- oauth-callback.html -->

<script src="<Your aWhere JavaScript API URL>"></script>
<script>
    awhere.identity
        .fetchToken(location)
        .then(() => {
            // authorized page
            location.href = '/';
        })
        .catch((err) => {
            // oauth flow authorized page
            location.href = '/sigin?' + err;
        });
</script>
```

## 2. Use the API

```js
import { Item, User } from '@awhere/api/core';
// Load item
Item.fromId('xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx').then((items) => {
    console.log('items', items);
});

// List users (admin only)
User.find().then((users) => {
    console.log('users', users);
});
```

### HTML Page

```html
<script src="<Your aWhere JavaScript API URL>"></script>
<script>
    // List your content
    awhere.core.Item.fromId('xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx').then((item) => {
        console.log('item', item);
    });

    // List users (admin only)
    awhere.core.User.find().then((users) => {
        console.log('users', users);
    });
</script>
```