JavaScript / TypeScript SDK¶

The PrimeStamp JavaScript SDK provides a client for the PrimeStamp API that works in both Node.js and browser environments. It supports TypeScript out of the box with full type definitions.

Installation¶

# npm
npm install @primestamp/sdk

# yarn
yarn add @primestamp/sdk

# pnpm
pnpm add @primestamp/sdk

Quick Start¶

import { PrimeStampClient } from "@primestamp/sdk";

const client = new PrimeStampClient({
  baseUrl: "https://api.primestamp.io",
  apiKey: "your-api-key",
});

// Stamp content
const stamp = await client.stampContent(Buffer.from("Hello, World!"));
console.log(`Stamp ID: ${stamp.id}`);

// Verify content
const result = await client.verify(stamp.id, Buffer.from("Hello, World!"));
console.log(`Verified: ${result.verified}`);

Client Configuration¶

const client = new PrimeStampClient({
  baseUrl: "https://api.primestamp.io",
  apiKey: "your-api-key",
  hashAlgorithm: "sha3-256",   // or "sha256"
  timeout: 30000,               // milliseconds
});

Option	Type	Default	Description
`baseUrl`	`string`	Required	PrimeStamp API endpoint.
`apiKey`	`string`	Required	API authentication key.
`hashAlgorithm`	`string`	`"sha3-256"`	Hash algorithm for content hashing.
`timeout`	`number`	`30000`	Request timeout in milliseconds.

Stamping¶

Stamp Raw Content¶

const stamp = await client.stampContent(contentBuffer, {
  metadata: { author: "alice", project: "research" },
  description: "Quarterly report Q4 2025",
});

Stamp a Pre-Computed Hash¶

const stamp = await client.stampHash("sha3-256:abc123def456...");

Stamp a File (Node.js)¶

import { readFile } from "fs/promises";

const content = await readFile("./report.pdf");
const stamp = await client.stampContent(content, {
  metadata: { filename: "report.pdf" },
});

Verification¶

const result = await client.verify(stampId, contentBuffer);
console.log(result.verified);    // boolean
console.log(result.timestamp);   // ISO 8601 string
console.log(result.contentHash); // hash string

// Verify by hash
const result = await client.verifyHash(stampId, "sha3-256:abc123...");

Listing Stamps¶

const stamps = await client.listStamps({
  limit: 20,
  offset: 0,
  after: "2025-01-01T00:00:00Z",
  before: "2025-12-31T23:59:59Z",
});

for (const stamp of stamps) {
  console.log(`${stamp.id}: ${stamp.contentHash}`);
}

Retrieving a Stamp¶

const stamp = await client.getStamp("stamp-id-here");
console.log(stamp.proof?.primeSignature);

Error Handling¶

import { PrimeStampError, NotFoundError } from "@primestamp/sdk";

try {
  const stamp = await client.getStamp("nonexistent-id");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error("Stamp not found");
  } else if (error instanceof PrimeStampError) {
    console.error(`API error: ${error.message}`);
  }
}

Browser Usage¶

The SDK works in browsers via bundlers (webpack, Vite, esbuild). Content hashing uses the Web Crypto API when available.

// Browser - hash a File object
const file = document.getElementById("fileInput").files[0];
const buffer = await file.arrayBuffer();
const stamp = await client.stampContent(new Uint8Array(buffer));

TypeScript Types¶

import type {
  Stamp,
  Proof,
  VerificationResult,
  StampOptions,
  ListOptions,
} from "@primestamp/sdk";

Framework Integrations

The JavaScript SDK can be used with any framework. For React applications, consider wrapping the client in a context provider. For Next.js, use the SDK in server actions or API routes to keep your API key server-side.

API Key Security

Never expose your API key in client-side browser code. Use a backend proxy or server-side rendering to keep the key confidential.