Digital Passport Hub JavaScript SDK

Easily interact with the Digital Passport Hub REST API from your Node.js or browser applications.

Installation

npm install @digital-passports/javascript-sdk

Usage

Node.js (Server)

Use this approach for server-side applications (Node.js, serverless, backend scripts):

const { DigitalPassport } = require('@digital-passports/javascript-sdk');

const dpp = new DigitalPassport({ apiKey: 'your_api_key' });

(async () => {
  const passports = await dpp.listPassports();
  console.log(passports);
})();

Browser (Frontend)

Use this approach for web applications running in the browser:

With a Bundler (Webpack, Vite, Parcel, etc.)

import { DigitalPassport } from '@digital-passports/javascript-sdk';

const dpp = new DigitalPassport({ apiKey: 'your_api_key' });

Directly in HTML (via CDN or UMD bundle)

<script src="https://unpkg.com/@digital-passports/javascript-sdk/dist/digital-passport-hub-javascript-sdk.umd.js"></script>
<script>
  const dpp = new window.DigitalPassport({ apiKey: 'your_api_key' });
  dpp.listPassports().then(console.log);
</script>

When to Use Each Module

• Node.js/Server: Use the standard import (require or import) for any backend or serverless environment. The SDK will automatically use Node.js-compatible HTTP requests.
• Browser:
  • If using a modern build tool (Webpack, Vite, etc.), use the ESM import (import { DigitalPassport } ...).
  • If you want to include the SDK directly in an HTML page (no build step), use the UMD bundle from the dist/ directory or a CDN. The SDK will attach itself to window.DigitalPassport.

API Reference

new DigitalPassport(options)

• options.apiKey (required): Your API key
• options.environment (optional): Defaults to 'production'

listPassports()

Returns a paginated list of all Digital Product Passports.

createPassport(data)

Creates a new Digital Product Passport.

• data: Object with at least sku and name fields

Error Handling

All methods throw errors with detailed messages if the API request fails.

Enhanced Error Codes

The SDK provides enhanced error codes on all errors thrown as DigitalPassportError:

• All error codes are available as the exported ErrorCode enum from the SDK.

| Code | Description | |------------------|------------------------------------------------------------------| | ErrorCode.NETWORK_ERROR | A network error occurred (DNS, offline, CORS, etc.) | | ErrorCode.VALIDATION_ERROR | Invalid or missing user-supplied data, or 4xx validation errors | | ErrorCode.AUTH_ERROR | Authentication or authorization error (401/403) | | ErrorCode.NOT_FOUND | Resource not found (404) | | ErrorCode.SERVER_ERROR | Server-side error (5xx) | | ErrorCode.HTTP_ERROR | Other HTTP errors (non-2xx, not covered above) | | ErrorCode.UNEXPECTED_ERROR | An unexpected error occurred (e.g., code bug, unknown exception) |

You can use these codes to handle errors more precisely:

import { ErrorCode } from '@digital-passports/javascript-sdk';

try {
  await dpp.listPassports();
} catch (err) {
  if (err.code === ErrorCode.NETWORK_ERROR) {
    // Show a network error message to the user
  } else if (err.code === ErrorCode.HTTP_ERROR) {
    // Handle API errors (e.g., invalid API key, 404, etc.)
  } else {
    // Handle unexpected errors
  }
}

TypeScript Support

Type definitions are included for autocompletion and type safety.

License

MIT