npm package: @naugtur/classificationfs
Description: Egnyte ClassificationFS specification and tooling
Latest version: 1.9.0-0

# ClassificationFS API

## API definition

https://storage.googleapis.com/pint-internal-static-hosting/classificationFS/docsCLFS.html


Use in your app along with other tools:
```js
const APIdefinition = require("classificationfs/APIdefinition");
```

## Installation 
```
npm install @naugtur/classificationfs
```

## ClassificationFS SDK

### Usage

```js
const CLFSSDK = require("classificationfs/sdk");
CLFSSDK.use(options);
```

**options**

|option|description|
|---|---|
|router|an express router to add the app to|
|protocol|optional, defaults to "https"|
|handlers|an object with handlers implementing operations on CLFS, see below for details|
|fileStreamErrorHandler|a function to call when file content streaming errors out. signature: (err, req, res) |
|authorization|an object related to Egnyte Protect oAuth process, see below for details|
|flags|a map of boolean flags to be returned in discovery|
|basePath|optional - if the router is mounted on a certain path, pass it here so that url generation tools work correctly|

**handlers**

You must implement at least `getDiff` or `getFolder`.
To generate URLs to subfolders in `getFolder`, use `req.helpers.folderURL` - it'll generate URLs pointing to the same folder endpoint with the `id` you choose to pass coming in as a param.
If `getDiff` or `getFolder` returns external file content URLs, that's all. Otherwise, `getFile` needs to be implemented to return the file stream and you can use `req.helpers.fileURL` to generate those URLs when listing folders.
`report` defaults to just console-logging the request body of the report. If you need something else, provide an implementation.  
`cleanUp` handles a request coming in from Egnyte when the source gets removed - it's optional and can be used to clean up any mappings or data.

`getDiff`,`getFolder`,`cleanUp` and `report` return:

```js
{
  body: JSON; //optional
  headers: {
  } //optional
}
```

`getFile` returns:

```js
{
    stream: file content stream reference //required
    headers: {} //optional
}
```

**helpers**

`req` passed to the handler has an additional non-standard field `helpers` with the following:

```js
folderUrl({ id }) => APPURL/fs/${id}
fileUrl({ id }) => APPURL/download/${id}
discoveryUrl({ storageId }) => APPURL/${storageId}
buildURL(anythingAtTheEnd) => APPURL/${anythingAtTheEnd}
```

#### Scaffolding of an app

```js
const CLFSSDK = require("classificationfs/sdk");
const express = require("express");

const app = express();

const { router, startAuth, getUrlHelpers } = CLFSSDK.use({
  router: express.Router(),
  authorization: {
    oauthCredentials: {
      clientId: "CLIENT_ID",
      clientSecret: "CLIENT_SECRET",
    },
    onError: ({ error, res }) => {
    
    },
    tokenReceiver: ({ token, authProcessId, res, helpers }) => {
    
    }
  },
  handlers: {
    async getFolder(req) {
      const id = req.params.folderId;

      req.helpers.folderURL({id:"someother folder id"})
      req.helpers.fileURL({id:"someother file id"})

      return { body: JSONbody };
    },
    async getDiff(req) {
      const cursor = req.query.cursor;

      req.helpers.fileURL({id:"someother file id"})

      return { body: JSONbody };
    },
    async getFile(req) {
      const id = req.params.fileId;
      return {
        stream: storage.createReadStream(id),
        headers: {
          "content-type": "application/octet-stream",
          "content-disposition": "attachment"
        }
      };
    }
    async report(req) {
      console.log(req.body)
    }
  }
});
app.use(router);
app.listen(1337);

```




## Mock server

```
npm install -g @naugtur/classificationfs
classificationfs-mock 8080
```

OR

```
npx -p @naugtur/classificationfs classificationfs-mock 8080
```

Port number is optional, defaults to 3000

### I need it to be HTTPS

The best way to go is to expose the mock via ngrok. 
Install ngrok and run 
```
ngrok http 3000
```
it will proxy your http server over to a https URL.

## Working with the repository

To run mockserver from repository, just do:
```
node mockserver/cli.js
```

Edit the API definitions in their respective folders

install node.js for tooling to work, then run `npm install` in the repo folder.

run `npm start` to generate html docs
run `npm test` to validate if the definition is syntactically correct.