tweaks for API classes, filled out commenting for docs, added jsdoc config

This commit is contained in:
Ro 2021-07-02 14:45:35 -07:00
parent 1f1c611afe
commit 13c9d05019
8 changed files with 1430 additions and 151 deletions

File diff suppressed because one or more lines are too long

View file

@ -1,4 +1,4 @@
import FipamoAdminAPI from "../../libraries/FipamoAdminAPI";
import FipamoAdminAPI, { TASK_SYNC_NAV } from "../../libraries/FipamoAdminAPI";
import NavActions from "../actions/NavActions";
import * as DataEvent from "../events/DataEvent";
import Notifications from "../ui/Notifications";
@ -26,7 +26,7 @@ export default class NavIndex {
onUpdate: () => {
new NavActions().syncMenu().then((data) => {
notify.alert("Updating Menu", null);
self.admin.syncNav(data).then((r) => {
self.admin.sync(TASK_SYNC_NAV, data).then((r) => {
if (r.type == DataEvent.MENU_UPDATED) {
notify.alert(r.message, true);
} else {

View file

@ -1,5 +1,8 @@
import SettingsActions from "../actions/SettingsActions";
import FipamoAdminAPI from "../../libraries/FipamoAdminAPI";
import Maintenance from "MaintenanceManager";
import FipamoAdminAPI, {
TASK_SYNC_SETTNIGS
} from "../../libraries/FipamoAdminAPI";
import * as DataEvent from "../../../src/com/events/DataEvent";
import Mailer from "../actions/Mailer";
import Notifications from "../ui/Notifications";
@ -27,7 +30,7 @@ export default class SettingsIndex {
.getInfo()
.then((data) => {
notify.alert("Saving Settings", null);
self.admin.syncSettings(data).then((r) => {
self.admin.sync(TASK_SYNC_SETTNIGS, data).then((r) => {
if (r.type == DataEvent.SETTINGS_UPDATED) {
notify.alert(r.message, true);
} else {
@ -170,9 +173,8 @@ export default class SettingsIndex {
}
handleImageUpload(type, files) {
notify.alert("Uploading Image... ", null);
let utils = new FipamoAdminAPI();
utils
.imageUpload(type, files)
let mm = new Maintenance();
mm.imageUpload(type, files)
.then((r) => {
if (r.type == DataEvent.AVATAR_UPLOADED) {
notify.alert(r.message, true);
@ -191,11 +193,11 @@ export default class SettingsIndex {
e.preventDefault();
e.stopPropagation();
let self = this;
let task = { task: "publish all pages" };
let task = { task: "PUBLISH_ALL" };
this.processing = true;
notify.alert("Publishing site...", null);
this.admin
.publishSite(task)
.publish(task)
.then((r) => {
self.processing = false;
notify.alert(r.message, true);

3
src/jsdoc.json Normal file
View file

@ -0,0 +1,3 @@
{
"plugins": ["plugins/markdown"]
}

View file

@ -27,12 +27,14 @@ export const TASK_PAGE_EDIT = "editPage";
export const TASK_PAGE_DELETE = "deletePage";
export const TASK_SEND_MAIL = "sendMail";
export const TASK_REINDEX_PAGE = "reIndexPages";
export const TASK_SYNC_SETTNIGS = "syncSite";
export const TASK_SYNC_NAV = "syncNav";
//** API STATUS **//
export const API_ACCESS_GOOD = "apiUseAuthorized";
export const API_ACCESS_BAD = "apiUseNotAuthorized";
/**
* A can of methods used to edit install settings, navigation pages.
* A can of methods used to edit install settings, navigation pages and content pages
*/
class FipamoAdminAPI {
@ -63,10 +65,22 @@ class FipamoAdminAPI {
});
}
/**
* Promise method for checking credentials. Must login to use Admin API.
* @param {object} data - json object that contains data for set up
* @property {string} handle - handle for site user
* @property {string} password - password for site user
* Promise method for authenticating and starting a session\
* **POST**`/api/v1/login`
* @param {Object[]} data - json object that contains data for set up
* @param {string} data[].handle - handle for site user
* @param {string} data[].password - password for site user
* @example
* api.login(data).then(response=>{
* console.log("RESPONSE", response);
* })
* @returns {object} json object that contains type and status of login request
```
{
"message":"Example Message of Affirmation or what you're missing!",
"type":"exampleType",
}
```
*/
login(data) {
return new Promise((resolve, reject) => {
@ -88,31 +102,59 @@ class FipamoAdminAPI {
});
}
/**
* Method for saving settings
* @param {object} data - json object that contains settings data set on the front-end
* @property {string} global.base_url - base url for site
* @property {string} global.title - site title
* @property {string} global.descriptions - brief site summary
* @property {string} global.background - url for site feature image for header
* @property {boolean} global.private - privacy state for site [disabled]
* @property {boolean} global.renderOnSave - property for publishing site when page saved [disabled]
* @property {string} global.theme - current theme for site
* @property {boolean} global.externalAPI - toggle for external API access
* @property {string} member.handle - current member handle
* @property {string} member.email - current member email
* @property {string} email.active - current email protocol being used
* @property {string} email.smtp.domain - url of smtp service being
* @property {string} email.smtp.email - email account of smtp service
* @property {string} email.smtp.password - password for email of smtp service
* @property {string} email.mailgun.domain - mailgun domain url
* @property {string} email.mailgun.key - mailgun key
* Method for saving site and navigation settings\
* **POST**`/api/v1/settings/:task`
* @param {string} task - settings being synced `config | navigation`
* @param {object[]} data - json object that contains settings data for [site] or [nav]
* @param {string} data[].global.base_url - base url for site [site]
* @param {string} data[].global.title - site title [site]
* @param {string} data[].global.descriptions - brief site summary [site]
* @param {string} data[].global.background - url for site feature image for header [site]
* @param {boolean} data[].global.private - privacy state for site [disabled] [site]
* @param {boolean} data[].global.renderOnSave - property for publishing site when page saved [disabled] [site]
* @param {string} data[].global.theme - current theme for site [site]
* @param {boolean} data[].global.externalAPI - toggle for external API access [site]
* @param {string} data[].member.handle - current member handle [site]
* @param {string} data[].member.email - current member email [site]
* @param {string} data[].email.active - current email protocol being used [site]
* @param {string} data[].email.smtp.domain - url of smtp service being [site]
* @param {string} data[].email.smtp.email - email account of smtp service [site]
* @param {string} data[].email.smtp.password - password for email of smtp service [site]
* @param {string} data[].email.mailgun.domain - mailgun domain url [site]
* @param {string} data[].email.mailgun.key - mailgun key [site]
*
* @param {string} data[].item.title - page title [nav]
* @param {string} data[].item.slug - url safe title [nav]
* @param {string} data[].item.uuid - unique identifier [nav]
* @param {string} data[].item.path - directory path to associated markdown file [nav]
* @example
* api.sync(TASK, data).then(response=>{
* console.log("RESPONSE", response);
* })
* @returns {object} json object that contains type and status of sync request
```
*
{
"message":"Example Message of Affirmation!",
"type":"exampleType",
}
```
*/
syncSettings(data) {
sync(task, data) {
return new Promise((resolve, reject) => {
let url = "";
switch (task) {
case "syncSite":
url = API_SETTINGS_SYNC;
break;
case "syncNav":
url = API_NAV_SYNC;
break;
}
this._request(
this.baseURL
? this.baseURL + API_SETTINGS_SYNC + "?key=" + this.key
: API_SETTINGS_SYNC + "?key=" + this.key,
? this.baseURL + url + "?key=" + this.key
: url + "?key=" + this.key,
TASK_SETTINGS_WRITE,
REQUEST_TYPE_POST,
CONTENT_TYPE_JSON,
@ -129,10 +171,21 @@ class FipamoAdminAPI {
/**
* Method for retrieving user authorizing user login
* @param {object} data - json object that contains task
* @property {string} task - publishing task [deprecated]
* @param {object[]} data - json object that contains task
* @param {string} data[].task - publishing task
* @example
* api.publish(TASK).then(response=>{
* console.log("RESPONSE", response);
* })
* @returns {object} json object that contains type and status of publis request
* ```
{
"message":"Example Message of Affirmation!",
"type":"exampleType",
}
* ```
*/
publishSite(data) {
publish(data) {
return new Promise((resolve, reject) => {
this._request(
//API_PUBLISH_PAGES,
@ -152,22 +205,34 @@ class FipamoAdminAPI {
}
/**
* Method for handling page creating and editing
* Method for handling page creating and editing\
* **POST**`/api/v1/page/:task`
* @param {string} task - current page action
* @param {object} data - form object that contains info for current page being edited/created
* @property {string} id - sequence id for page
* @property {string} uuid - unique identifier for page
* @property {string} layout - current page layout
* @property {string} current_title - saved url save title for persistence when changing title
* @property {string} content - markdown body of page
* @property {string} title - current title of page
* @property {string} created - date page was created
* @property {string} slug - url safe string of page title
* @property {string} tags - comma separated list of tags
* @property {boolean} menu - property that indicates page is included in site menu
* @property {boolean} featured - property that indicates page is featured
* @property {boolean} published - property that indicates page is public
* @property {input} feature_image - main image for page
* @param {object[]} form - form object that contains info for current page being edited/created
* @param {string} form[].id - sequence id for page, leave empty for new page
* @param {string} form[].uuid - unique identifier for page, leave empty for new page
* @param {string} form[].layout - current page layout
* @param {string} form[].current_title - saved url save title for persistence when changing title, leave empty for new page
* @param {string} form[].content - markdown body of page
* @param {string} form[].title - current title of page
* @param {string} form[].created - date page was created, leave empty for new page
* @param {string} form[].slug - url safe string of page title
* @param {string} form[].tags - comma separated list of tags
* @param {boolean} form[].menu - property that indicates page is included in site menu
* @param {boolean} form[].featured - property that indicates page is featured
* @param {boolean} form[].published - property that indicates page is public
* @param {input} form[].feature_image - main image for page
* @example
* api.pageActions(TASK, data).then(response=>{
* console.log("RESPONSE", response);
* })
* @returns {object} json object that contains type and status of page edit request
```
{
"message":"Example Message of Affirmation!",
"type":"exampleType",
}
```
*/
pageActions(task, data) {
let url, event, content;
@ -218,34 +283,21 @@ class FipamoAdminAPI {
}
/**
* Method for saving pages to be included in main site navigation
* @param {object} data - json object that contains items to be included in main site navigation
* @property {string} item.title - page title
* @property {string} item.slug - url safe title
* @property {string} item.uuid - unique identifier
* @property {string} item.path - directory path to associated markdown file
*/
syncNav(data) {
return new Promise((resolve, reject) => {
this._request(
this.baseURL ? this.baseURL + API_NAV_SYNC : API_NAV_SYNC,
TASK_SETTINGS_WRITE,
REQUEST_TYPE_POST,
CONTENT_TYPE_JSON,
data
)
.then((result) => {
resolve(result);
})
.catch((err) => {
reject(err);
});
});
* Method for sending mail (if completed in settings)\
* **POST**`/api/v1/mailer`
* @param {object[]} message - json object that contains items to be included in main site navigation
* @param {string} message[].content - message to send
* @example
* api.sendMail(message).then(response=>{
* console.log("RESPONSE", response);
* })
* @returns {object} json object that contains type and status of page edit request
```
{
"message":"Example Message of Affirmation!",
"type":"exampleType"
}
/**
* Method for sending mail
* @param {object} message - json object that contains items to be included in main site navigation
* @property {string} content - message to send
```
*/
sendMail(message) {
return new Promise((resolve, reject) => {
@ -264,27 +316,7 @@ class FipamoAdminAPI {
});
});
}
/**
* Maintenance method to clean up page sequencing [disabled]
* @param {object} data - json object that contains items to be included in main site navigation
*/
reindexPages(data) {
return new Promise((resolve, reject) => {
this._request(
this.baseURL ? this.baseURL + API_REINDEX_PAGES : API_REINDEX_PAGES,
TASK_REINDEX_PAGE,
REQUEST_TYPE_POST,
CONTENT_TYPE_JSON,
data
)
.then((result) => {
resolve(result);
})
.catch((err) => {
reject(err);
});
});
}
//--------------------------
// private
//--------------------------

View file

@ -19,15 +19,13 @@ export const API_GET_TAGS = "/api/v1/page/tags";
export const TASK_GET_CONTENT = "retrieveContent";
/**
* Fipamo Content API
* A bag of methods for getting page info from an install.
* To use remotely, include url of install and user key found in settings in the Dashboard.
* A bag of methods for getting content from an install.
*/
class FipamoContentAPI {
/**
* @constructor
* @param {string} baseURL - url of site; uses local when empty
* @param {string} key - user api key
* @param {string} baseURL - url of install, defaults to local
* @param {string} key - user api key found in Settings
* @author Ro
*/
constructor(baseURL = null, key = null) {
@ -38,14 +36,61 @@ class FipamoContentAPI {
}
/**
* Promise method for retrieving page data
* @param {string} type - type of pages being retrieved; null value defaults to published
* *Promise method for retrieving page data*\
* **GET**`/api/v1/page/:type`
* @param {string} type - type of pages (`published | menu | featured`) being retrieved; null value defaults to `published`
* @example
* api.pages('published').then(pages=>{
* console.log("Pages Object", pages);
* })
* @returns {object} json object that contains pages of requested type
*
* *pages object example*
* ```
{
"pages":
[
{
"id":1,
"uuid":"uuid-for-entry",
"title":"Entry Title",
"feature":"/path/to/image.jpg",
"path":"2020/09",
"layout":"page",
"tags":"these, are, tags",
"author":"your-name",
"created":"2020 Sep Tue 01",
"updated":"2020 Sep Tue 01",
"deleted":false,
"menu":false,
"featured":false,
"published":true,
"slug":"entry-title",
"content":"Premium Content"
},
{
"id":2,
"uuid":"uuid-for-entry",
"title":"Another Title",
"feature":"/path/to/image.jpg",
"path":"2020/09",
"layout":"page",
"tags":"these, are, tags",
"author":"your-name",
"created":"2020 Sep Tue 01",
"updated":"2020 Sep Tue 01",
"deleted":false,
"menu":false,
"featured":false,
"published":true,
"slug":"another-title",
"content":"Premium Content"
}
],
"totalItems":2
}
* ```
*
*/
pages(type = null) {
//set url based on request type
@ -76,13 +121,36 @@ class FipamoContentAPI {
});
}
/**
* Promise method for retrieving single page
* *Promise method for retrieving single page*\
* **GET** `/api/v1/page/single/:id`
* @param {string} id - uuid of desired page
* @example
* api.page("a-uuid-for-a-page").then(page=>{
console.log("Page Object", page);
* })
* @returns {object} json object that contains data for requested page
*
* *page object example*
* ```
{
"id":1,
"uuid":"uuid-for-entry",
"title":"Entry Title",
"feature":"/path/to/image.jpg",
"path":"2020/09",
"layout":"page",
"tags":"these, are, tags",
"author":"your-name",
"created":"2020 Sep Tue 01",
"updated":"2020 Sep Tue 01",
"deleted":false,
"menu":false,
"featured":false,
"published":true,
"slug":"entry-title",
"content":"Premium Content"
}
* ```
*/
page(id) {
return new Promise((resolve, reject) => {
@ -103,12 +171,55 @@ class FipamoContentAPI {
}
/**
* Promise method for retrieving all tags used by pages
* *Promise method for retrieving all tags used by pages*\
* **GET** `/api/v1/page/tags`
* @example
* api.tags().then(tags=>{
console.log("Tags Object", tags);
* })
* @returns {object} json object that contains tags used by pages
* @returns {object} json object that contains site tags and page stubs associated with said tag
*
* *tags object example*
* ```
[
{
"tag_name":"this is a tag",
"slug":"this-is-a-tag",
"pages":
[
{
"title":"This is a title",
"slug":"this-is-a-title",
"path":"2021/04"
},
{
"title":"This is another title",
"slug":"this-is-another-title",
"path":"2020/10"
}
]
},
{
"tag_name":"this is another tag",
"slug":"this-is-another-tag",
"pages":
[
{
"title":"This is a title",
"slug":"this-is-a-title",
"path":"2021/04"
},
{
"title":"This is another title",
"slug":"this-is-another-title",
"path":"2020/10"
}
]
}
]
* ```
*/
tags() {
return new Promise((resolve, reject) => {

1195
src/package-lock.json generated

File diff suppressed because it is too large Load diff

View file

@ -11,6 +11,7 @@
"@babel/core": "^7.14.6",
"@babel/eslint-parser": "^7.14.5",
"animejs": "^3.2.1",
"apidoc": "^0.28.1",
"bulma": "^0.9.2",
"caret-pos": "^2.0.0",
"jsdoc": "^3.6.7",
@ -20,5 +21,10 @@
"devDependencies": {
"eslint": "^7.28.0",
"eslint-plugin-babel": "^5.3.1"
},
"apidoc": {
"name": "Fipamo API",
"version": "1.0.0",
"description": "The most chill API for the most chill blog framework"
}
}