@outlawdesigns/loe-rest-client 1.0.0

package/README.md

@@ -0,0 +1,198 @@
+# LOE REST Client (JavaScript)
+
+A lightweight JavaScript/Node.js client for interacting with the **Library of Everything (LOE)** REST API using OAuth2 authentication.
+This package provides modular access to LOE models—anime, docs, episodes, movies, songs, and holding-bay items—along with robust token handling and a shared singleton interface.
+
+---
+
+## 🚀 Features
+
+* 🔐 **OAuth2 client credentials authentication**
+* 🔄 **Automatic token refresh**
+* 📦 Organized model access:
+
+  * `anime`
+  * `doc`
+  * `episode`
+  * `movie`
+  * `song`
+  * `holdingbay` (special pre-ingest items)
+* 🧩 **Singleton mode** for shared instances
+* ⚙️ Clean, consistent `axios`-based API
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @outlawdesigns/loe-rest-client
+```
+
+---
+
+## 🧠 Basic Usage
+
+### Initialize the API Client
+
+```js
+import loeClient from '@outlawdesigns/loe-rest-client';
+
+// Create the singleton instance
+loeClient.init('https://loe-service.outlawdesigns.io', 'openid profile email');
+
+// Initialize OAuth provider
+await loeClient.get().auth.init(
+  'https://auth.outlawdesigns.io/oauth2/token',
+  'your-client-id',
+  'your-client-secret'
+);
+
+// Perform OAuth2 client credentials flow
+await loeClient.get().auth.clientCredentialFlow(
+  'openid profile email',
+  [ 'https://loe-service.outlawdesigns.io' ]
+);
+
+// Example call: fetch 3 most recent songs
+const recent = await loeClient.get().songs.getRecent(3);
+console.log(recent);
+```
+
+### Token Verification Example
+
+```js
+const token = loeClient.get().auth.getAccessToken();
+
+const tokenResp = await loeClient.get().auth.verifyAccessToken(
+  token,
+  ['https://loe-service.outlawdesigns.io']
+);
+
+console.log(tokenResp);
+```
+
+### Accessing the Singleton Anywhere
+
+```js
+import loeClient from '@outlawdesigns/loe-rest-client';
+
+const song = await loeClient.get().song.get(42);
+```
+
+---
+
+## 🔐 Authentication Flow
+
+The LOE REST Client uses **`@outlawdesigns/authenticationclient`** to handle:
+
+* Token acquisition
+* Token refresh
+* Attaching `Authorization: Bearer <token>` headers
+* Token verification
+
+### Typical Flow
+
+```js
+// 1. init() creates the API + axios wrapper
+loeClient.init(apiUrl, oauthScope);
+
+// 2. Provide OAuth endpoint + credentials
+await loeClient.get().auth.init(authUrl, clientId, clientSecret);
+
+// 3. Client credentials flow to obtain tokens
+await loeClient.get().auth.clientCredentialFlow(oauthScope, [apiUrl]);
+
+// 4. Make API calls
+const movies = await loeClient.get().movie.getAll();
+```
+
+---
+
+## 🧩 Available Model Modules
+
+### 🎵 `api.song`
+
+Supports LOE’s rich music feature set.
+
+| Method                            | Description                      |
+| --------------------------------- | -------------------------------- |
+| `getAll()`                        | Get all songs                    |
+| `get(id)`                         | Fetch a song                     |
+| `create(songObj)`                 | Create a song                    |
+| `search(field, query)`            | Search songs                     |
+| `browse(field)`                   | Browse unique values for a field |
+| `getRecent(limit)`                | Fetch `n` most recent songs      |
+| `getMyPlaylists()`                | Retrieve user playlists          |
+| `getPlaylist(id)`                 | Get a specific playlist          |
+| `savePlaylist(obj)`               | Save playlist                    |
+| `rate(id, rating)`                | Rate a song                      |
+| `getRating(id)`                   | Fetch a rating                   |
+| `count()`                         | Count total songs                |
+| `group(field)`                    | Group by field                   |
+| `getRandomPlaylist(genre, limit)` | Randomized playlist              |
+
+---
+
+### 🎬 `api.movie`
+
+Standard CRUD + metadata operations.
+
+### 📺 `api.episode`
+
+Episode-level metadata for TV/anime content.
+
+### 🎭 `api.anime`
+
+Anime metadata (similar to episode model).
+
+### 📄 `api.doc`
+
+Document/Ebook metadata.
+
+### 📥 `api.holdingbay`
+
+Read-only staging area for media not yet classified:
+
+| Method        | Description                         |
+| ------------- | ----------------------------------- |
+| `getMovies()` | Items possibly classified as movies |
+| `getSongs()`  | Music-type items                    |
+| `getTv()`     | TV/episode candidates               |
+| `getComics()` | Comic content                       |
+
+---
+
+## 🧱 Project Structure
+
+```
+src/
+├── core.js
+├── singleton.js
+├── models/
+│   ├── anime.js
+│   ├── doc.js
+│   ├── episode.js
+│   ├── movie.js
+│   ├── song.js
+│   └── holdingbay.js
+└── formData.js
+```
+
+---
+
+## ⚙️ Creating a Direct Client (Non-Singleton)
+
+```js
+import { createApiClient } from '@outlawdesigns/loe-rest-client/core.js';
+
+const api = createApiClient(apiUrl, oauthScope);
+await api.auth.init(authUrl, clientId, clientSecret);
+await api.auth.clientCredentialFlow(oauthScope, [apiUrl]);
+```
+
+---
+
+## 👤 Author
+
+Maintained by **Outlaw Designs**
+[https://github.com/outlawdesigns-io](https://github.com/outlawdesigns-io)

package/index.js

@@ -0,0 +1,3 @@
+import apiClientSingleton from './src/singleton.js';
+
+export default apiClientSingleton;

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@outlawdesigns/loe-rest-client",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "type": "module",
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "@outlawdesigns/authenticationclient": "^2.1.1",
+    "axios": "^1.13.2"
+  }
+}

package/src/core.js

@@ -0,0 +1,54 @@
+import axios from 'axios';
+import authClient from '@outlawdesigns/authenticationclient';
+
+import createAnime from './models/anime.js';
+import createDocs from './models/doc.js';
+import createEpisodes from './models/episode.js';
+import createHoldingbay from './models/holdingBay.js';
+import createMovies from './models/movie.js';
+import createSongs from './models/song.js';
+
+export function createApiClient(baseURL, requestedScope){
+  const oauthScope = requestedScope; //the scope(s) for this app
+  const oauthResource = baseURL;
+  const oauthRefreshBuffer = 300;
+  const axiosInstance = axios.create({baseURL:baseURL});
+  authClient.onTokenUpdate((token)=>{
+    axiosInstance.defaults.headers.common['Authorization'] = `Bearer ${token}`;
+  });
+  axiosInstance.interceptors.request.use(async (config)=>{
+    const token = authClient.getAccessToken();
+    if(!token) throw new Error(`Authenticate before making API calls.`);
+    const refreshToken = authClient.getRefreshToken();
+    let user;
+    if(refreshToken){
+      try{
+        user = await authClient.verifyAccessToken(token,[oauthResource]);
+      }catch(err){
+        console.log(err);
+        return;
+      }
+      const now = Math.floor(Date.now() / 1000);
+      const timeDiffSeconds = user.exp - now;
+      if(timeDiffSeconds <= oauthRefreshBuffer){
+        try{
+          await authClient.refreshToken(oauthScope,[oauthResource]);
+        }catch(err){
+          console.log(err);
+          return;
+        }
+      }
+    }
+    config.headers['Authorization'] = `Bearer ${authClient.getAccessToken()}`;
+    return config;
+  });
+  return {
+    auth:authClient,
+    movies:createMovies(axiosInstance),
+    songs:createSongs(axiosInstance),
+    holdingBay:createHoldingbay(axiosInstance),
+    episodes:createEpisodes(axiosInstance),
+    docs:createDocs(axiosInstance),
+    anime:createAnime(axiosInstance)
+  }
+}

package/src/models/anime.js

@@ -0,0 +1,65 @@
+const resource = '/anime';
+
+export default function createAnime(axios){
+  return {
+    async getAll(){
+      const res = await axios.get(`${resource}`);
+      return res.data;
+    },
+    async get(id){
+      if(!id){
+        throw new Error('Id argument reguired.');
+      }
+      const res = await axios.get(`${resource}/${id}`);
+      return res.data;
+    },
+    async create(animeObj){
+      const res = await axios.post(`${resource}`,animeObj);
+      return res.data;
+    },
+    async search(field, query){
+      const res = await axios.get(`${resource}/search/${field}/${query}`);
+      return res.data;
+    },
+    async browse(field){
+      const res = await axios.get(`${resource}/browse/${field}`);
+      return res.data;
+    },
+    async getRecent(limit){
+      const res = await axios.get(`${resource}/recent/${limit}`);
+      return res.data;
+    },
+    async getMyPlaylists(){
+      const res = await axios.get(`${resource}/list/`);
+      return res.data;
+    },
+    async getPlaylist(id){
+      const res = await axios.get(`${resource}/list/${id}`);
+      return res.data;
+    },
+    async savePlaylist(playlistObj){
+      const res = await axios.post(`${resource}/list`,playlistObj);
+      return res.data;
+    },
+    async rate(animeId, rating){
+      const res = await axios.post(`${resource}/rate/${animeId}`,{rating:rating});
+      return res.data;
+    },
+    async getRating(id){
+      const res = await axios.get(`${resource}/rate/${id}`);
+      return res.data;
+    },
+    async count(){
+      const res = await axios.get(`${resource}/count/`);
+      return res.data;
+    },
+    async group(field){
+      const res = await axios.get(`${resource}/group/${field}`);
+      return res.data;
+    },
+    async getRandomPlaylist(genre, limit){
+      const res = await axios.get(`${resource}/random/${genre}/${limit}`);
+      return res.data;
+    }
+  }
+}

package/src/models/doc.js

@@ -0,0 +1,65 @@
+const resource = '/doc';
+
+export default function createDocs(axios){
+  return {
+    async getAll(){
+      const res = await axios.get(`${resource}`);
+      return res.data;
+    },
+    async get(id){
+      if(!id){
+        throw new Error('Id argument reguired.');
+      }
+      const res = await axios.get(`${resource}/${id}`);
+      return res.data;
+    },
+    async create(docObj){
+      const res = await axios.post(`${resource}`,docObj);
+      return res.data;
+    },
+    async search(field, query){
+      const res = await axios.get(`${resource}/search/${field}/${query}`);
+      return res.data;
+    },
+    async browse(field){
+      const res = await axios.get(`${resource}/browse/${field}`);
+      return res.data;
+    },
+    async getRecent(limit){
+      const res = await axios.get(`${resource}/recent/${limit}`);
+      return res.data;
+    },
+    async getMyPlaylists(){
+      const res = await axios.get(`${resource}/list/`);
+      return res.data;
+    },
+    async getPlaylist(id){
+      const res = await axios.get(`${resource}/list/${id}`);
+      return res.data;
+    },
+    async savePlaylist(playlistObj){
+      const res = await axios.post(`${resource}/list`,playlistObj);
+      return res.data;
+    },
+    async rate(docId, rating){
+      const res = await axios.post(`${resource}/rate/${docId}`,{rating:rating});
+      return res.data;
+    },
+    async getRating(id){
+      const res = await axios.get(`${resource}/rate/${id}`);
+      return res.data;
+    },
+    async count(){
+      const res = await axios.get(`${resource}/count/`);
+      return res.data;
+    },
+    async group(field){
+      const res = await axios.get(`${resource}/group/${field}`);
+      return res.data;
+    },
+    async getRandomPlaylist(genre, limit){
+      const res = await axios.get(`${resource}/random/${genre}/${limit}`);
+      return res.data;
+    }
+  }
+}

package/src/models/episode.js

@@ -0,0 +1,65 @@
+const resource = '/episode';
+
+export default function createEpisodes(axios){
+  return {
+    async getAll(){
+      const res = await axios.get(`${resource}`);
+      return res.data;
+    },
+    async get(id){
+      if(!id){
+        throw new Error('Id argument reguired.');
+      }
+      const res = await axios.get(`${resource}/${id}`);
+      return res.data;
+    },
+    async create(episodeObj){
+      const res = await axios.post(`${resource}`,episodeObj);
+      return res.data;
+    },
+    async search(field, query){
+      const res = await axios.get(`${resource}/search/${field}/${query}`);
+      return res.data;
+    },
+    async browse(field){
+      const res = await axios.get(`${resource}/browse/${field}`);
+      return res.data;
+    },
+    async getRecent(limit){
+      const res = await axios.get(`${resource}/recent/${limit}`);
+      return res.data;
+    },
+    async getMyPlaylists(){
+      const res = await axios.get(`${resource}/list/`);
+      return res.data;
+    },
+    async getPlaylist(id){
+      const res = await axios.get(`${resource}/list/${id}`);
+      return res.data;
+    },
+    async savePlaylist(playlistObj){
+      const res = await axios.post(`${resource}/list`,playlistObj);
+      return res.data;
+    },
+    async rate(episodeId, rating){
+      const res = await axios.post(`${resource}/rate/${episodeId}`,{rating:rating});
+      return res.data;
+    },
+    async getRating(id){
+      const res = await axios.get(`${resource}/rate/${id}`);
+      return res.data;
+    },
+    async count(){
+      const res = await axios.get(`${resource}/count/`);
+      return res.data;
+    },
+    async group(field){
+      const res = await axios.get(`${resource}/group/${field}`);
+      return res.data;
+    },
+    async getRandomPlaylist(genre, limit){
+      const res = await axios.get(`${resource}/random/${genre}/${limit}`);
+      return res.data;
+    }
+  }
+}

package/src/models/holdingBay.js

@@ -0,0 +1,22 @@
+const resource = '/holdingbay';
+
+export default function createHoldingbay(axios){
+  return {
+    async getMovies(){
+      const res = await axios.get(`${resource}/movies`);
+      return res.data;
+    },
+    async getSongs(){
+      const res = await axios.get(`${resource}/music`);
+      return res.data;
+    },
+    async getTv(){
+      const res = await axios.get(`${resource}/tv`);
+      return res.data;
+    },
+    async getComics(){
+      const res = await axios.get(`${resource}/comic`);
+      return res.data;
+    }
+  }
+}

package/src/models/movie.js

@@ -0,0 +1,65 @@
+const resource = '/movie';
+
+export default function createMovies(axios){
+  return {
+    async getAll(){
+      const res = await axios.get(`${resource}`);
+      return res.data;
+    },
+    async get(id){
+      if(!id){
+        throw new Error('Id argument reguired.');
+      }
+      const res = await axios.get(`${resource}/${id}`);
+      return res.data;
+    },
+    async create(movieObj){
+      const res = await axios.post(`${resource}`,movieObj);
+      return res.data;
+    },
+    async search(field, query){
+      const res = await axios.get(`${resource}/search/${field}/${query}`);
+      return res.data;
+    },
+    async browse(field){
+      const res = await axios.get(`${resource}/browse/${field}`);
+      return res.data;
+    },
+    async getRecent(limit){
+      const res = await axios.get(`${resource}/recent/${limit}`);
+      return res.data;
+    },
+    async getMyPlaylists(){
+      const res = await axios.get(`${resource}/list/`);
+      return res.data;
+    },
+    async getPlaylist(id){
+      const res = await axios.get(`${resource}/list/${id}`);
+      return res.data;
+    },
+    async savePlaylist(playlistObj){
+      const res = await axios.post(`${resource}/list`,playlistObj);
+      return res.data;
+    },
+    async rate(movieId, rating){
+      const res = await axios.post(`${resource}/rate/${movieId}`,{rating:rating});
+      return res.data;
+    },
+    async getRating(id){
+      const res = await axios.get(`${resource}/rate/${id}`);
+      return res.data;
+    },
+    async count(){
+      const res = await axios.get(`${resource}/count/`);
+      return res.data;
+    },
+    async group(field){
+      const res = await axios.get(`${resource}/group/${field}`);
+      return res.data;
+    },
+    async getRandomPlaylist(genre, limit){
+      const res = await axios.get(`${resource}/random/${genre}/${limit}`);
+      return res.data;
+    }
+  }
+}

package/src/models/song.js

@@ -0,0 +1,65 @@
+const resource = '/song';
+
+export default function createSongs(axios){
+  return {
+    async getAll(){
+      const res = await axios.get(`${resource}`);
+      return res.data;
+    },
+    async get(id){
+      if(!id){
+        throw new Error('Id argument reguired.');
+      }
+      const res = await axios.get(`${resource}/${id}`);
+      return res.data;
+    },
+    async create(songObj){
+      const res = await axios.post(`${resource}`,songObj);
+      return res.data;
+    },
+    async search(field, query){
+      const res = await axios.get(`${resource}/search/${field}/${query}`);
+      return res.data;
+    },
+    async browse(field){
+      const res = await axios.get(`${resource}/browse/${field}`);
+      return res.data;
+    },
+    async getRecent(limit){
+      const res = await axios.get(`${resource}/recent/${limit}`);
+      return res.data;
+    },
+    async getMyPlaylists(){
+      const res = await axios.get(`${resource}/list/`);
+      return res.data;
+    },
+    async getPlaylist(id){
+      const res = await axios.get(`${resource}/list/${id}`);
+      return res.data;
+    },
+    async savePlaylist(playlistObj){
+      const res = await axios.post(`${resource}/list`,playlistObj);
+      return res.data;
+    },
+    async rate(songId, rating){
+      const res = await axios.post(`${resource}/rate/${songId}`,{rating:rating});
+      return res.data;
+    },
+    async getRating(id){
+      const res = await axios.get(`${resource}/rate/${id}`);
+      return res.data;
+    },
+    async count(){
+      const res = await axios.get(`${resource}/count/`);
+      return res.data;
+    },
+    async group(field){
+      const res = await axios.get(`${resource}/group/${field}`);
+      return res.data;
+    },
+    async getRandomPlaylist(genre, limit){
+      const res = await axios.get(`${resource}/random/${genre}/${limit}`);
+      return res.data;
+    }
+  }
+}

package/src/singleton.js

@@ -0,0 +1,26 @@
+import { createApiClient } from './core.js';
+
+let instance = null;
+
+function init(baseURL){
+  if(instance){
+    if(instance.axios.defaults.baseURL !== baseURL){
+      throw new Error(`API client already initialized with ${instance.axios.defaults.baseURL}`);
+    }
+    return instance;
+  }
+  instance = createApiClient(baseURL);
+  return instance;
+}
+
+function getInstance(){
+  if(!instance){
+    throw new Error('API client not initialized. Call init(baseURL) first.');
+  }
+  return instance;
+}
+
+export default{
+  init,
+  get: getInstance
+};