CRIPT Web SDK

1 - Introduction

This repository is a TypeScript port of the CRIPT's Python SDK. This library is responsible for talking to the CRIPT app API and providing utility classes. Any front-end application can use it (whether in TypeScript or Javascript).

The diagram below put in evidence the abstraction layer provided by the SDK. On the left part, the CRIPT Editor app imports the WebSDK to use CRIPT app's API. The principle is exactly the same with any ingestion tool using the Python SDK.

2 - How to use?

Pick a WebSDK version compatible with a given the API version. Use the table below to choose the right version:

| API | Web SDK | Progress | | ----| --------| ---------| | 0.6.0 | ^0.13.3 | Contain most of the API | | 0.4.3 | ^0.4 | typings and API to get primary nodes |

Note: API version and CRIPTapp version are currently the same thing, in the future the CRIPTapp will have a separated versioning like the WebSDK does.

Install it:

npm i @cript-web/[email protected]

Once installed, from your JS/TS code import the library this way:

import { newClient } from '@cript-web/sdk'

// create a client
const api = await newClient({
  host: 'criptapp.org',
  refreshJWT: Cookies.get('refreshjwt') // in lower case. You might replace this call depending on the library you use to load cookies from your application.
  tls: true
})

// get a project
const project     = await api.projects.getFromUid('your-project-id');

// get a paginator from project's collections URL
const collections = await api.collections.getAllFromUrl(project.collections);

// do stuff
collections.currentPage.results.forEach( (collection) => { /** do stuff */})

IAPIClient is still WIP, please find usage proposal here.

3 - How to develop?

3.1 - Install

Nothing special, just clone th repo and run npm i from its root directory.

Note: if you need to run e2e tests, you will need to install a CRIPTapp locally.

3.2 - Testing

Unit tests

To perform basic unit tests run:

npm run watch_test

This will watch for modification and will trigger the build and tests automatically while you are working.

"End-to-End" tests

Warning: There is no real e2e tests right now, existing tests are based on node and do not run in a browser.

To perform advanced tests requiring an instance of the CRIPTapp running locally, you have to setup an .env file at the package root folder, insert the following data:

CRIPT_HOST=127.0.0.1
CRIPT_COOKIE="sessionid=xxxxxx;csrftoken=yyyyyyyy"
CRIPT_TLS=false
CRIPT_LOG_CONFIG=false
CRIPT_PROJECTS=["ce434573-b8a0-4f9b-94a6-f5a4e2aa3ffb"]
CRIPT_COLLECTIONS=["1b9c7c80-6239-4b2c-9758-30aa9d6441eb"]

In case you enable TLS, run export NODE_TLS_REJECT_UNAUTHORIZED=0 from your command line before to run tests, it will bypass SSL security. There is also a script ./rune2e.sh that will do that for you and start to run tests in watch mode.

Then, to get the session id, log in your local instance, and open the debugging tools. Locate the cookies and copy/paste the value to your .env. Currently, there is no mechanism to login to CRIPTapp out of its embedded front-end.

Then, run the following command:

npm run watch_e2e

3.3 - Documentation

To read technical documentation open ./docs/typedoc/index.html

TODO:

• Tutorials: convert python tutorials?

3.4 - How to develop for the websdk and an app using it at the same time?

Clone this repository and from your project's folder type

cd path/to/websdk
npm link
cd path/to/your/app
npm link @cript-web/sdk

This will link dynamically the package without touching the package.json (which is good since you don't want to push a package pointing to an unpublished dependency).

3.5 - How to publish?

First, create a new package version by running

npm version --patch|minor|major x.y.z

help: running npm version will give you the current version of the package

This will update package.json and create a commit with a tag (vx.y.z) automatically. Then, push that tag:

git push --tag

When a tag is pushed to Github, a Github Actions will build and push the npm package to our @cript-web organisation.

You must see the package here once done, if not contact your lead.

Note: an NPM_TOKEN is required to push. This environment variable is defined as a secret in production environment. Require admin privileges to update it. It is impossible to see it.

4 - Credits

Package author: MIT | CRIPT

This repository is based on a template from Luke Edwards, check original readme.