adapt-authoring-api 0.0.1

package/.eslintignore

@@ -0,0 +1 @@
+node_modules

package/.eslintrc

@@ -0,0 +1,14 @@
+{
+  "env": {
+      "browser": false,
+      "node": true,
+      "commonjs": false,
+      "es2020": true
+  },
+  "extends": [
+      "standard"
+  ],
+  "parserOptions": {
+      "ecmaVersion": 2020
+  }
+}

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,55 @@
+name: Bug Report
+description: File a bug report
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Please describe the issue
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+      description: Tell us what should have happened
+  - type: textarea
+    id: repro-steps
+    attributes:
+      label: Steps to reproduce
+      description: Tell us how to reproduce the issue
+    validations:
+      required: true
+  - type: input
+    id: aat-version
+    attributes:
+      label: Authoring tool version
+      description: What version of the Adapt authoring tool are you running?
+    validations:
+      required: true
+  - type: input
+    id: fw-version
+    attributes:
+      label: Framework version
+      description: What version of the Adapt framework are you running?
+  - type: dropdown
+    id: browsers
+    attributes:
+      label: What browsers are you seeing the problem on?
+      multiple: true
+      options:
+        - Firefox
+        - Chrome
+        - Safari
+        - Microsoft Edge
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      render: sh

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature request
+description: Request a new feature
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to request a new feature in the Adapt authoring tool! The Adapt team will consider all new feature requests, but unfortunately cannot commit to every one.
+  - type: textarea
+    id: description
+    attributes:
+      label: Feature description
+      description: Please describe your feature request
+    validations:
+      required: true
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Can you work on this feature?
+      description: If you are able to commit your own time to work on this feature, it will greatly increase the liklihood of it being implemented by the core dev team. Otherwise, it will be triaged and prioritised alongside the core team's current priorities.
+      options:
+        - label: I can contribute

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

package/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+[//]: # (Please title your PR according to eslint commit conventions)
+[//]: # (See https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint#eslint-convention for details)
+
+[//]: # (Add a link to the original issue)
+
+[//]: # (Delete as appropriate)
+### Fix
+* A sentence describing each fix
+
+### Update
+* A sentence describing each udpate
+
+### New
+* A sentence describing each new feature
+
+### Breaking
+* A sentence describing each breaking change
+
+[//]: # (List appropriate steps for testing if needed)
+### Testing
+1. Steps for testing
+
+[//]: # (Mention any other dependencies)
+
+

package/.github/workflows/labelled_prs.yml

@@ -0,0 +1,16 @@
+name: Add labelled PRs to project
+
+on:
+  pull_request:
+    types: [ labeled ]
+
+jobs:
+  add-to-project:
+    if: ${{ github.event.label.name == 'dependencies' }}
+    name: Add to main project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v0.1.0
+        with:
+          project-url: https://github.com/orgs/adapt-security/projects/5
+          github-token: ${{ secrets.PROJECTS_SECRET }}

package/.github/workflows/new.yml

@@ -0,0 +1,19 @@
+name: Add to main project
+
+on:
+  issues:
+    types:
+      - opened
+  pull_request:
+    types:
+      - opened
+
+jobs:
+  add-to-project:
+    name: Add to main project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v0.1.0
+        with:
+          project-url: https://github.com/orgs/adapt-security/projects/5
+          github-token: ${{ secrets.PROJECTS_SECRET }}

package/adapt-authoring.json

@@ -0,0 +1,9 @@
+{
+  "module": false,
+  "documentation": {
+    "enable": true,
+    "manualPages": {
+      "writing-an-api.md": "basics"
+    }
+  }
+}

package/conf/config.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "defaultCacheLifespan": {
+      "description": "Default lifespan of data cache",
+      "type": "string",
+      "isTimeMs": true,
+      "default": "5s"
+    },
+    "defaultPageSize": {
+      "description": "Default size of page",
+      "type": "number",
+      "default": 100
+    },
+    "maxPageSize": {
+      "description": "Maximum page size",
+      "type": "number",
+      "default": 250
+    }
+  }
+}

package/docs/writing-an-api.md

@@ -0,0 +1,135 @@
+# Writing an API
+
+_**Note:** before using this functionality, it is worth having an understanding of how to write basic custom modules first. See [this page](`adapt-authoring-api` module) for more._
+
+The `adapt-authoring-api` module makes defining custom APIs simple by providing abstract classes and utilities you can use in your own modules to replace the common boilerplate code required when writing an API.
+
+By extending the [AbstractAPIModule](../class/adapt_authoring_restructure/adapt-authoring-api/lib/module.js~AbstractApiModule.html) class, you get the following as standard:
+- Boiler-plate code for defining router and endpoints
+- Default handlers for incoming HTTP requests (with support for querying)
+- Support for custom middleware
+- Auto-loading of database schemas
+- Automated (and overridable) database interaction
+- Default permissions
+
+## Defining your API
+
+To define an API, all you need to do is override the `setValues` function, making sure to change the values as appropriate.
+
+See the below table for all values:
+
+| Attribute | Type | Description | Optional |
+| --------- | ---- | ----------- | -------- |
+| `root` | `String` | This value will be used as the route for any URLs (e.g. `/api/mymodule`). For APIs which deal with collections of data, the general rule is to use the plural form (ie. `/api/items`). | `false` |
+| `router` | `Router` | The Router instance used for HTTP requests. If not defined, a new router will be created using the `root` value. | `true` |
+| `routes` | `Array<ApiRoute>` | Definitions for any routes to be added to the API router. | `false` |
+| `collectionName` | `String` | Default DB collection to store data to (can be overridden by individual handlers). | `false` |
+
+### Defining routes
+
+Before your API can handle HTTP requests, you must define which routes the router should respond to. If your module extends AbstractApiModule, this is simply a case of setting the [`routes`](../class/node_modules/adapt-authoring-api/lib/abstractApiModule.js~AbstractApiModule.html#instance-member-routes) instance variable:
+
+```js
+this.routes = [
+  // route config here
+]
+```
+
+#### General tips
+The Adapt server module maps to Express functionality as closely as possible, and as such adopts the same middleware/handler concepts (with a few minor changes). It is therefore very useful to have some understanding of how the Express stack works, particularly with regards to the execution order of middleware and handlers. For more details on route handling, see the [official Express documentation](https://expressjs.com/en/guide/routing.html).
+
+Here are a few useful notes/tips:
+
+- The `route` attribute of each route definition is very powerful, and handles params/queries/etc. in the same way as Express (see [the Express docs](https://expressjs.com/en/guide/routing.html) for more).
+- Use the API's middleware to perform any tasks which are common to all routes, such as checking and formatting the request data
+- You only need to specify route handlers for the routes/HTTP methods you want to enable, access will be blocked to any route/HTTP method combinations you haven't defined
+- You can run route-specific middleware by adding it as a handler to the route config (see example 2. below)
+
+#### Using the default route configuration
+Instead of defining each route yourself, the AbstractApiModule class also gives you a set of default routes which you can use if you wish:
+```js
+[
+  // POST, no params
+  {
+    route: '/',
+    modifying: true,
+    handlers: {
+      post: this.requestHandler()
+    }
+  },
+  // GET, optional _id param
+  {
+    route: '/:_id?',
+    handlers: {
+      get: this.requestHandler()
+    }
+  },
+  // PUT/DELETE, mandatory _id param
+  {
+    route: '/:_id',
+    modifying: true,
+    handlers: {
+      put: this.requestHandler(),
+      delete: this.requestHandler()
+    }
+  },
+  // POST custom query handler
+  {
+    route: '/query',
+    validate: false,
+    handlers: {
+      post: this.queryHandler()
+    }
+  }
+];
+```
+To use the above configuration, you simply need to call the `useDefaultRouteConfig` function:
+```js
+async setValues() {
+  this.useDefaultRouteConfig();
+}
+```
+
+### Example configurations
+```js
+/**
+* Basic configuration
+*/
+async setValues() {
+  const server = await this.app.waitForModule('server');
+  this.root = 'myapi';
+  this.collectionName = 'mycollection';
+  this.router = server.api.createChildRouter('myapi'); // optional
+  this.router.addMiddleware(this.myMiddleware);
+  this.routes = [
+    {
+      route: '/',
+      handlers: { // if you need reference to 'this' in your handler, remember to bind
+        get: this.myRequestHandler.bind(this)
+      }
+    },
+    {
+      route: '/two',
+      handlers: { // example of route-level middleware
+        post: [ this.myOtherMiddleware, this.myPostHandler ]
+      }
+    }
+  ];
+}
+/**
+* Custom route configuration
+*/
+async setValues() {
+  // @note other values omitted for brevity
+  this.routes = [
+    {
+      route: '/',
+      schemaName: 'myschema', // can specify custom schema/collection like this
+      collectionName: 'myothercollection',
+      handlers: {
+        get: this.myRequestHandler.bind(this)
+      }
+    }
+  ];
+}
+```

package/errors/errors.json

@@ -0,0 +1,32 @@
+{
+  "API_MODULE_INVALID_CLASS": {
+    "data": {
+      "name": "Name of the module"
+    },
+    "description": "Module does not extend AbstractApiModule",
+    "statusCode": 500
+  },
+  "HTTP_METHOD_NOT_SUPPORTED": {
+    "data": {
+      "method": "The invalid HTTP method"
+    },
+    "description": "HTTP method for a given request is not supported",
+    "statusCode": 404
+  },
+  "NO_COLL_NAME": {
+    "description": "module is missing a collection name",
+    "statusCode": 500
+  },
+  "NO_ROOT_OR_ROUTER_DEF": {
+    "description": "module is missing both a root and router definition",
+    "statusCode": 500
+  },
+  "NO_ROUTES_DEF": {
+    "description": "module is missing API routes definition",
+    "statusCode": 500
+  },
+  "NO_SCHEMA_DEF": {
+    "description": "No json schema has been defined",
+    "statusCode": 404
+  }
+}

package/index.js

@@ -0,0 +1,7 @@
+/**
+ * Abstract API utilities
+ * @namespace api
+ */
+export { default as AbstractApiModule } from './lib/AbstractApiModule.js'
+export { default as AbstractApiUtils } from './lib/AbstractApiUtils.js'
+export { default } from './lib/AbstractApiModule.js'