From 0b488446eeb94e0ba2ad759b94d10d27369908eb Mon Sep 17 00:00:00 2001
From: 0xSage <n@pragmatic.vc>
Date: Fri, 27 Oct 2023 10:59:45 +0700
Subject: [PATCH] docs: store, events, ref docs

---
 docs/docs/apps/azure-openai.md                |   4 +
 docs/docs/apps/rag.md                         |   4 +
 docs/docs/reference/coreservice.md            | 272 +-----------------
 docs/docs/reference/events.md                 |  51 ++++
 .../{models_catalog.md => model-catalog.md}   |   6 +-
 docs/docs/reference/plugins_catalog.md        |   6 -
 docs/docs/reference/preferences.md            |   6 +
 docs/docs/reference/store.md                  |  15 +
 docs/sidebars.js                              |  12 +
 9 files changed, 103 insertions(+), 273 deletions(-)
 create mode 100644 docs/docs/apps/azure-openai.md
 create mode 100644 docs/docs/apps/rag.md
 create mode 100644 docs/docs/reference/events.md
 rename docs/docs/reference/{models_catalog.md => model-catalog.md} (94%)
 delete mode 100644 docs/docs/reference/plugins_catalog.md
 create mode 100644 docs/docs/reference/preferences.md
 create mode 100644 docs/docs/reference/store.md

diff --git a/docs/docs/apps/azure-openai.md b/docs/docs/apps/azure-openai.md
new file mode 100644
index 000000000..b55131039
--- /dev/null
+++ b/docs/docs/apps/azure-openai.md
@@ -0,0 +1,4 @@
+---
+sidebar_position: 1
+title: "Azure OpenAI integration"
+---
diff --git a/docs/docs/apps/rag.md b/docs/docs/apps/rag.md
new file mode 100644
index 000000000..e0f697b9a
--- /dev/null
+++ b/docs/docs/apps/rag.md
@@ -0,0 +1,4 @@
+---
+sidebar_position: 1
+title: "Data retrieval app"
+---
diff --git a/docs/docs/reference/coreservice.md b/docs/docs/reference/coreservice.md
index 08233565a..328489bc3 100644
--- a/docs/docs/reference/coreservice.md
+++ b/docs/docs/reference/coreservice.md
@@ -1,278 +1,20 @@
 ---
 sidebar_position: 1
-title: "@janhq/core"
+title: "CoreService"
 ---
 
-## @janhq/core
-
-> The module includes functions for communicating with core APIs, registering plugin extensions, and exporting type definitions.
+`CoreService` provides an interface for implementing custom methods in Jan.
+It lets you define shared behavior across your custom application, like your app handles state, models, or inferencing behavior.
 
 ## Usage
 
-### Import the package
-
 ```js
-// javascript
-const core = require("@janhq/core");
-
-// typescript
-import * as core from "@janhq/core";
+import { CoreService, ... } from "@janhq/core";
 ```
 
-### Register Plugin Extensions
+## CoreService
 
-Every plugin must define an `init` function in its main entry file to initialize the plugin and register its extensions with the Jan platform.
-
-You can `register` any function as a plugin extension using `CoreServiceAPI` below. For example, the `DataService.GetConversations` entry name can be used to register a function that retrieves conversations.
-
-Once the extension is registered, it can be used by other plugins or components in the Jan platform. For example, a UI component might use the DataService.GetConversations extension to retrieve a list of conversations to display to the user.
-
-```js
-import { RegisterExtensionPoint, DataService } from "@janhq/core";
-
-function getConversations() {
-  // Your logic here
-}
-
-export function init({ register }: { register: RegisterExtensionPoint }) {
-  register(DataService.GetConversations, getConversations.name, getConversations);
-}
-```
-
-### Interact with Local Data Storage
-
-The Core API allows you to interact with local data storage. Here are a couple of examples of how you can use it:
-
-#### Insert Data
-
-You can use the store.insertOne function to insert data into a specific collection in the local data store.
-
-```js
-import { store } from "@janhq/core";
-
-function insertData() {
-  store.insertOne("conversations", { name: "meow" });
-  // Insert a new document with { name: "meow" } into the "conversations" collection.
-}
-```
-
-#### Get Data
-
-To retrieve data from a collection in the local data store, you can use the `store.findOne` or `store.findMany` function. It allows you to filter and retrieve documents based on specific criteria.
-
-store.getOne(collectionName, key) retrieves a single document that matches the provided key in the specified collection.
-store.getMany(collectionName, selector, sort) retrieves multiple documents that match the provided selector in the specified collection.
-
-```js
-import { store } from "@janhq/core";
-
-function getData() {
-  const selector = { name: "meow" };
-  const data = store.findMany("conversations", selector);
-  // Retrieve documents from the "conversations" collection that match the filter.
-}
-```
-
-#### Update Data
-
-You can update data in the local store using these functions:
-
-store.updateOne(collectionName, key, update) updates a single document that matches the provided key in the specified collection.
-store.updateMany(collectionName, selector, update) updates multiple documents that match the provided selector in the specified collection.
-
-```js
-function updateData() {
-  const selector = { name: "meow" };
-  const update = { name: "newName" };
-  store.updateOne("conversations", selector, update);
-  // Update a document in the "conversations" collection.
-}
-```
-
-#### Delete Data
-
-You can delete data from the local data store using these functions:
-
-store.deleteOne(collectionName, key) deletes a single document that matches the provided key in the specified collection.
-store.deleteMany(collectionName, selector) deletes multiple documents that match the provided selector in the specified collection.
-
-```js
-function deleteData() {
-  const selector = { name: "meow" };
-  store.deleteOne("conversations", selector);
-  // Delete a document from the "conversations" collection.
-}
-```
-
-### Events
-
-You can subscribe to NewMessageRequest events by defining a function to handle the event and registering it with the events object:
-
-```js
-import { events } from "@janhq/core";
-
-function handleMessageRequest(message: NewMessageRequest) {
-  // Your logic here. For example:
-  // const response = openai.createChatCompletion({...})
-}
-function registerListener() {
-  events.on(EventName.OnNewMessageRequest, handleMessageRequest);
-}
-// Register the listener function with the relevant extension points.
-export function init({ register }) {
-  registerListener();
-}
-```
-
-In this example, we're defining a function called handleMessageRequest that takes a NewMessageRequest object as its argument. We're also defining a function called registerListener that registers the handleMessageRequest function as a listener for NewMessageRequest events using the on method of the events object.
-
-```js
-import { events } from "@janhq/core";
-
-function handleMessageRequest(data: NewMessageRequest) {
-  // Your logic here. For example:
-   const response = openai.createChatCompletion({...})
-   const message: NewMessageResponse = {
-    ...data,
-    message: response.data.choices[0].message.content
-   }
-  // Now emit event so the app can display in the conversation
-   events.emit(EventName.OnNewMessageResponse, message)
-}
-```
-
-### Preferences
-
-To register plugin preferences, you can use the preferences object from the @janhq/core package. Here's an example of how to register and retrieve plugin preferences:
-
-```js
-import { PluginService, preferences } from "@janhq/core";
-
-const pluginName = "your-first-plugin";
-const preferenceKey = "";
-const preferenceName = "Your First Preference";
-const preferenceDescription = "This is for example only";
-const defaultValue = "";
-
-export function init({ register }: { register: RegisterExtensionPoint }) {
-  // Register preference update handlers. E.g. update plugin instance with new configuration
-  register(PluginService.OnPreferencesUpdate, pluginName, onPreferencesUpdate);
-
-  // Register plugin preferences. E.g. Plugin need apiKey to connect to your service
-  preferences.registerPreferences <
-    string >
-    (register, pluginName, preferenceKey, preferenceName, preferenceDescription, defaultValue);
-}
-```
-
-In this example, we're registering preference update handlers and plugin preferences using the preferences object. We're also defining a PluginName constant to use as the name of the plugin.
-
-To retrieve the values of the registered preferences, we're using the get method of the preferences object and passing in the name of the plugin and the name of the preference.
-
-```js
-import { preferences } from "@janhq/core";
-
-const pluginName = "your-first-plugin";
-const preferenceKey = "apiKey";
-
-const setup = async () => {
-  // Retrieve apiKey
-  const apiKey: string = (await preferences.get(pluginName, preferenceKey)) ?? "";
-};
-```
-
-### Access Core API
-
-To access the Core API in your plugin, you can follow the code examples and explanations provided below.
-
-##### Import Core API and Store Module
-
-In your main entry code (e.g., `index.ts`), start by importing the necessary modules and functions from the `@janhq/core` library.
-
-```js
-// index.ts
-import * as core from "@janhq/core";
-```
-
-#### Perform File Operations
-
-The Core API also provides functions to perform file operations. Here are a couple of examples:
-
-#### Download a File
-
-You can download a file from a specified URL and save it with a given file name using the core.downloadFile function.
-
-```js
-function downloadModel(url: string, fileName: string) {
-  core.downloadFile(url, fileName);
-}
-```
-
-#### Delete a File
-
-To delete a file, you can use the core.deleteFile function, providing the path to the file you want to delete.
-
-```js
-function deleteModel(filePath: string) {
-  core.deleteFile(path);
-}
-```
-
-#### Execute plugin module in main process
-
-To execute a plugin module in the main process of your application, you can follow the steps outlined below.
-
-##### Import the `core` Object
-
-In your main process code (e.g., `index.ts`), start by importing the `core` object from the `@janhq/core` library.
-
-```js
-// index.ts
-import * as core from "@janhq/core";
-```
-
-##### Define the Module Path
-
-Specify the path to the plugin module you want to execute. This path should lead to the module file (e.g., module.js) that contains the functions you wish to call.
-
-```js
-// index.ts
-const MODULE_PATH = "data-plugin/dist/module.js";
-```
-
-##### Define the Function to Execute
-
-Create a function that will execute a function defined in your plugin module. In the example provided, the function `getConversationMessages` is created to invoke the `getConvMessages` function from the plugin module.
-
-```js
-// index.ts
-function getConversationMessages(id: number) {
-  return core.invokePluginFunc(MODULE_PATH, "getConvMessages", id);
-}
-
-export function init({ register }: { register: RegisterExtensionPoint }) {
-  register(DataService.GetConversationMessages, getConversationMessages.name, getConversationMessages);
-}
-```
-
-##### Define Your Plugin Module
-
-In your plugin module (e.g., module.ts), define the logic for the function you wish to execute. In the example, the function getConvMessages is defined with a placeholder comment indicating where your logic should be implemented.
-
-```js
-// module.ts
-function getConvMessages(id: number) {
-  // Your logic here
-}
-
-module.exports = {
-  getConvMessages,
-};
-```
-
-## CoreService API
-
-The `CoreService` type is an exported union type that includes:
+The `CoreService` type bundles the following services:
 
 - `StoreService`
 - `DataService`
@@ -350,4 +92,4 @@ The `PluginService` enum includes plugin cycle handlers:
 - `OnStart`: Handler for starting. E.g. Create a collection.
 - `OnPreferencesUpdate`: Handler for preferences update. E.g. Update instances with new configurations.
 
-For more detailed information on each of these components, please refer to the source code.
\ No newline at end of file
+For more detailed information on each of these components, please refer to the source code.
diff --git a/docs/docs/reference/events.md b/docs/docs/reference/events.md
new file mode 100644
index 000000000..5f3a03ab5
--- /dev/null
+++ b/docs/docs/reference/events.md
@@ -0,0 +1,51 @@
+---
+sidebar_position: 2
+title: "events"
+---
+
+`events` lets you receive events about actions that take place in the app, like when a user sends a new message.
+
+You can then implement custom logic handlers for such events.
+
+## Usage
+
+```js
+import { events } from "@janhq/core";
+```
+
+## EventName
+
+The `EventName` enum bundles the following events:
+
+- `OnNewConversation`
+- `OnNewMessageRequest`
+- `OnNewMessageResponse`
+- `OnMessageResponseUpdate`
+- `OnDownloadUpdate`
+- `OnDownloadSuccess`
+- `OnDownloadError`
+
+## event.on
+
+Adds an observer for an event.
+
+```js
+const on: (eventName: string, handler: Function) => void = (eventName, handler);
+```
+
+## event.emit
+
+Emits an event.
+
+```js
+const emit: (eventName: string, object: any) => void = (eventName, object);
+```
+
+## event.off
+
+Removes an observer for an event.
+
+```js
+const off: (eventName: string, handler: Function) => void =
+  (eventName, handler);
+```
diff --git a/docs/docs/reference/models_catalog.md b/docs/docs/reference/model-catalog.md
similarity index 94%
rename from docs/docs/reference/models_catalog.md
rename to docs/docs/reference/model-catalog.md
index fdf4b7a63..ace0f922f 100644
--- a/docs/docs/reference/models_catalog.md
+++ b/docs/docs/reference/model-catalog.md
@@ -1,9 +1,10 @@
 ---
-sidebar_position: 1
-title: "@janhq/models"
+sidebar_position: 3
+title: "Model catalog"
 ---
 
 ### Install
+
 Using yarn:
 
 ```shell
@@ -43,6 +44,7 @@ console.log(MODEL_CATALOG_URL);
 ```
 
 ### How to contribute
+
 1. Go to [Jan Models](https://github.com/janhq/models)
 2. Create an Issue for new model (template incoming)
 3. Create a PR for new model familly (See [The Bloke zephyr 7B alpha GGUF](https://github.com/janhq/models/blob/main/TheBloke-zephyr-7B-alpha-GGUF.json)) to `main` branch
diff --git a/docs/docs/reference/plugins_catalog.md b/docs/docs/reference/plugins_catalog.md
deleted file mode 100644
index 18011f6a2..000000000
--- a/docs/docs/reference/plugins_catalog.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-sidebar_position: 1
-title: "@janhq/plugins"
----
-
-To be updated. In the mean time, please refer to our [ADR 007 - Plugin catalog](https://github.com/janhq/jan/blob/main/adr/adr-007-jan-plugin-catalog.md)
\ No newline at end of file
diff --git a/docs/docs/reference/preferences.md b/docs/docs/reference/preferences.md
new file mode 100644
index 000000000..807665863
--- /dev/null
+++ b/docs/docs/reference/preferences.md
@@ -0,0 +1,6 @@
+---
+sidebar_position: 4
+title: "preferences"
+---
+
+## Usage
diff --git a/docs/docs/reference/store.md b/docs/docs/reference/store.md
new file mode 100644
index 000000000..32efae979
--- /dev/null
+++ b/docs/docs/reference/store.md
@@ -0,0 +1,15 @@
+---
+sidebar_position: 3
+title: "store"
+---
+
+`store` is a helper library for working with Jan app's local storage database.
+
+Jan ships with a [pouchDB](https://pouchdb.com/) client side noSQL db to persist usage state
+store (logic from @data-plugin which implements StoreService)
+
+## Usage
+
+```js
+import { store } from "@janhq/core";
+```
diff --git a/docs/sidebars.js b/docs/sidebars.js
index a93d3e22d..0f8bb619c 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -71,6 +71,18 @@ const sidebars = {
         },
       ],
     },
+    {
+      type: "category",
+      label: "Apps",
+      collapsible: true,
+      collapsed: false,
+      items: [
+        {
+          type: "autogenerated",
+          dirName: "apps",
+        },
+      ],
+    },
     {
       type: "category",
       label: "Tutorials",