perma-js-sdk

A JavaScript library to interact with Perma.cc's REST API.

⚠️ This is an early version.

Summary

• Getting started
• Stack and compatibility
• API documentation
• Development CLI
• Environment variables
• Publishing a new version

Getting started

Installation as a dependency

You may use npm or your favorite JavaScript package manager to install perma-js-sdk as a dependency.

npm install @harvard-lil/perma-js-sdk

Directly in the browser

This library can be imported directly in the browser. You may use a service such as unpkg.com to import its latest version from npmjs.org.

import { PermaAPI } from "https://unpkg.com/@harvard-lil/perma-js-sdk@latest/index.js";

Quick Example

Here a quick example of how to use the PermaAPI class to interact with Perma.cc's API. See the API Documentation for details.

import { PermaAPI } from "@harvard-lil/perma-js-sdk";

try {
  const api = new PermaAPI(API_KEY);
  const archive = await api.createArchive("https://lil.harvard.edu");
  console.log(`Archive created -- guid: ${archive.guid}`);
}
catch(err) {
  // ...
}

☝️ Back to summary

Stack and compatibility

Stack

This library, by design, has no runtime dependency and does not require a build step in most cases.

Compatibility notes

This library:

• [...] uses the Fetch API.Versions of Node.js that do not support fetch() may instead use node-fetch and make it globally accessible.
• [...] is ES module-based and doesn't support CommonJS syntax.
• [...] was written so it can be run without transpiling in:
  • Latest Chromium
  • Latest Gecko
  • Latest WebKit
  • Latest Node.js (+ latest Node.js LTS with node-fetch)

☝️ Back to summary

API documentation

Reference

• PermaAPI class documentation (Automatically generated)
• Associated types documentation (Automatically generated)

Notes

• This project uses JSDoc and is compatible with IntelliSense (Examples: [1] [2]).

Misc

• Perma.cc's REST API reference

☝️ Back to summary

Development CLI

docgen

npm run docgen

Refreshes files under /doc using JSDoc comments in index.js and types.js.

test-unit

npm run test-unit

Runs index.unit.test.js using Jest.

test-integration

npm run test-integration

Runs index.integration.test.js using Jest. This test suite requires the TESTS_API_KEY and TESTS_FORCE_BASE_URL environment variables to be set.

test-integration-local

npm run test-integration-local

Same as test-integration but:

• Reads environment variables from .env file if available
• Ignores TLS certificates errors (so the tests can be run against a local instance of the Perma API)

☝️ Back to summary

Environment variables

Scope: Integration tests

The following environment variables are only used in the context of the integration tests suite.

| Name | Required? | Description | | --- | --- | --- | | TESTS_API_KEY | Yes | API key to be used to perform integration tests. Can be of any type of account. | | TESTS_FORCE_BASE_URL | No | Base API url to be used to perform integration tests. If not set, will default to https://api.perma.cc. |

☝️ Back to summary

Publishing a new version

Once changes have been merged to develop and a new version is ready, please follow these steps to deploy a new version of the package:

1. Run unit tests: npm run test-unit
2. Run integration tests: npm run test-integration-local
3. Update documentation: npm run docgen
4. Update NPM package version number: npm version patch --no-git-tag-version
5. Publish on NPM: npm publish --access public
6. Commit and push changes to develop
7. PR and merge to main, with version number as PR title.

ℹ️ Steps 1-5 can be replaced by ./test-and-publish.sh

You will need access to the @harvard-lil organization on npmjs.org to publish new versions of the package.

☝️ Back to summary