@cript-web/sdk
v0.18.3
Published
A TypeScript port of the CRIPT's Python SDK
Downloads
118
Readme
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.