@truestamp/truestamp-js NPM

Truestamp JS

Description

A tiny zero-dependency Truestamp SDK library written in Typescript for Deno, Node.js, and modern browsers.

Usage of this library requires an active Truestamp account, and an API key in order to communicate with the API back end.

Features

Small library size
Zero dependencies
Built with Typescript
Promise based API (async/await)
Supports Deno (ESM), Node.js (CommonJS), and modern browsers (ESM, UMD)
esm.sh CDN support
SkyPack CDN support
JSDELIVR CDN support
UNPKG CDN support

API Documentation

The TypeScript API documentation for this project is generated and published upon each new release.

Documentation about the Truestamp server-side REST API can be found at https://docs.truestamp.com/.

Installation

How to install and import the Truestamp code using different runtime environments.

Setup

In your NPM project root.

npm install @truestamp/truestamp-js --save

Require the @truestamp/truestamp-js CommonJS module in your project and initialize it with your api key.

Import

const Truestamp = require("@truestamp/truestamp-js")
...

Setup

Import the @truestamp/truestamp-js ESM module in your project via esm.sh and initialize it with your apiKey.

Import

// Load module from esm.sh CDN, pinned to a specific version.
import Truestamp from "https://esm.sh/@truestamp/truestamp-js@0.15.0"
...

Import

You can use a <script> tag in the browser to load a specific version of the library from several supported CDN's. Replace the pinned version in the link with the version you use in your app. You can use the ES Modules or UMD builds for browser support.

<!-- load from JSDELIVR CDN latest (using latest not recommended for production use, pin a version) -->
<!-- See : https://www.jsdelivr.com/package/npm/@truestamp/truestamp-js -->
<script src="https://cdn.jsdelivr.net/npm/@truestamp/truestamp-js@latest/dist/truestamp.umd.min.js"></script>

The JS files available for each version can be browsed at JSDELIVR

<!-- load from UNPKG CDN latest (using latest not recommended for production use, pin a version) -->
<!-- See : https://unpkg.com/browse/@truestamp/truestamp-js/ -->
<script src="https://unpkg.com/@truestamp/truestamp-js"></script>

API Usage Example

Each function provided on the Truestamp class returns a result in the form of an object with two properties success and data.

success is a boolean that indicates if the request completed successfully or not.
data is an Object representing the response from the API and can represent a valid response or an error response.

After each call to a Truestamp class function you should test whether it was successful and respond appropriately in your code.

You should not expect this library to throw exceptions. If it does please file a bug.

// See installation section for your runtime environment.
import Truestamp from "@truestamp/truestamp-js"

// A TRUESTAMP_API_KEY environment variable can also be set in your
// environment in place of providing the `apiKey` value as an argument.
const truestamp = new Truestamp({ apiKey: "%yourApiKey%" })

const myHash =
  "e728e4adeb8c0606fce4686552338622efeb8c63b53d072a323a4914d1aa5c07"

// Create new Item
const { success, data } = await truestamp.createItem(
  {
    itemData: [
      {
        hash: myHash,
        hashType: "sha-256",
      },
    ],
  },
  { skipCF: false, skipOE: false }
)

if (!success) {
  console.log("API call failed")
  console.log(data) // Contains Error JSON
  process.exit(1)
}

// Success! Contains good response JSON
console.log("createItem", data)

Examples

There are working code examples for Deno, Node.js, and the Web in the /examples directory. Take a look at the examples/README.md for usage instructions.

Contributing

We'd love you to join our network of contributors. Please read CONTRIBUTING.md for help getting started.

Testing

The tests run actual requests against the public API. You'll need to export the following environment variables locally.

export TRUESTAMP_ENV=development
export TRUESTAMP_API_KEY=...

Releasing

Commit changes, and merge any pull requests to the main branch
Bump the version field in package.json
Cut a new release
The new release will trigger a workflow to build, test, and publish the package to Github Package Registry and NPM.js.