IAIndex SDK for Node.js

Official IAIndex SDK for Node.js applications. Track and verify AI content usage with cryptographic receipts and attestations.

Features

• Publisher Tools: Register and verify content with cryptographic signatures
• Client Tools: Access content and send usage receipts
• ECDSA Signing: Secure cryptographic signatures using secp256k1
• Receipt Generation: Automatic receipt creation and submission
• API Integration: Seamless integration with IAIndex API
• TypeScript Support: Full TypeScript definitions included

Installation

npm install @iaindex/sdk
# or
yarn add @iaindex/sdk

Quick Start

For Publishers

const { IAIndexPublisher, CryptoUtils } = require('@iaindex/sdk');

// Generate a key pair (or use existing private key)
const keyPair = CryptoUtils.generateKeyPair();

// Initialize publisher
const publisher = new IAIndexPublisher({
  domain: 'yourdomain.com',
  privateKey: keyPair.privateKey,
  name: 'Your Publication',
  contact: '[email protected]'
});

// Initialize connection to API
await publisher.initialize();

// Add content entries
await publisher.addEntry({
  url: 'https://yourdomain.com/article',
  title: 'Article Title',
  author: 'Author Name',
  publishedDate: new Date().toISOString(),
  license: { type: 'CC-BY-4.0' }
});

// Generate signed index file
const index = await publisher.generateIndex();
console.log('Index generated:', index);

For AI Clients

const { IAIndexClient, CryptoUtils } = require('@iaindex/sdk');

// Generate a key pair (or use existing private key)
const keyPair = CryptoUtils.generateKeyPair();

// Initialize client
const client = new IAIndexClient({
  clientId: 'your-client-id',
  privateKey: keyPair.privateKey,
  name: 'Your AI Model',
  organization: 'Your Organization'
});

// Initialize connection to API
await client.initialize();

// Access content and get metadata
const content = await client.accessContent('https://example.com/article');

// Send usage receipt
await client.sendReceipt(content, {
  purpose: 'training',
  context: 'language-model-pretraining',
  modelId: 'my-model-v1'
});

API Reference

IAIndexPublisher

Constructor

new IAIndexPublisher(options: PublisherOptions)

Options:

• domain (string): Your verified domain
• privateKey (string): Private key for signing (hex string)
• name (string): Publisher name
• contact (string): Contact email
• apiBaseUrl (string, optional): Custom API base URL

Methods

async initialize(): Promise<void>

Initialize publisher and authenticate with API. Must be called before other operations.

async addEntry(entry: ContentEntry): Promise<string>

Add a content entry to the index.

const entryId = await publisher.addEntry({
  url: 'https://example.com/article',
  title: 'Article Title',
  author: 'Author Name',
  publishedDate: '2024-01-01T00:00:00Z',
  content: 'Article content...',
  license: {
    type: 'CC-BY-4.0',
    terms: 'Attribution required'
  }
});

async generateIndex(): Promise<IndexFile>

Generate a signed index file containing all entries.

const index = await publisher.generateIndex();
// Returns: { domain, publisher, entries, signature, timestamp, version }

async verifyReceipt(receipt: Receipt): Promise<boolean>

Verify a receipt signature.

const isValid = await publisher.verifyReceipt(receipt);

getEntries(): ContentEntry[]

Get all added entries.

getPublicKey(): string

Get the publisher's public key.

getDomain(): string

Get the publisher's domain.

IAIndexClient

Constructor

new IAIndexClient(options: ClientOptions)

Options:

• clientId (string): Unique client identifier
• privateKey (string): Private key for signing (hex string)
• name (string, optional): Client/model name
• organization (string, optional): Organization name
• apiBaseUrl (string, optional): Custom API base URL

Methods

async initialize(): Promise<void>

Initialize client and authenticate with API. Must be called before other operations.

async accessContent(url: string): Promise<ContentMetadata>

Access content and retrieve metadata.

const metadata = await client.accessContent('https://example.com/article');
// Returns: { url, title, author, publishedDate, license, publisher }

async sendReceipt(content: ContentMetadata, usage: UsageInfo): Promise<boolean>

Send a usage receipt for accessed content.

const success = await client.sendReceipt(content, {
  purpose: 'training',  // 'training' | 'inference' | 'research'
  context: 'language-model-pretraining',
  datasetId: 'dataset-v1',
  modelId: 'model-v1'
});

async getVerifiedPublishers(): Promise<any[]>

Get list of verified publishers.

getClientId(): string

Get the client ID.

getPublicKey(): string

Get the client's public key.

CryptoUtils

Utility class for cryptographic operations.

Methods

static generateKeyPair(): KeyPair

Generate a new ECDSA key pair.

const keyPair = CryptoUtils.generateKeyPair();
// Returns: { privateKey: string, publicKey: string }

static sign(data: string | object, privateKey: string): string

Sign data with a private key.

static verify(data: string | object, signature: string, publicKey: string): boolean

Verify a signature with a public key.

static getPublicKey(privateKey: string): string

Derive public key from private key.

static hash(data: string | object): string

Generate SHA-256 hash of data.

static generateId(): string

Generate a random ID.

TypeScript Support

The SDK is written in TypeScript and includes full type definitions.

import { IAIndexPublisher, IAIndexClient, CryptoUtils, ContentEntry } from '@iaindex/sdk';

const entry: ContentEntry = {
  url: 'https://example.com/article',
  title: 'Article Title',
  author: 'Author Name',
  publishedDate: new Date().toISOString(),
  license: { type: 'CC-BY-4.0' }
};

Examples

Complete Publisher Example

const { IAIndexPublisher, CryptoUtils } = require('@iaindex/sdk');

async function main() {
  // Generate or load key pair
  const keyPair = CryptoUtils.generateKeyPair();
  console.log('Private Key:', keyPair.privateKey);
  console.log('Public Key:', keyPair.publicKey);

  // Create publisher
  const publisher = new IAIndexPublisher({
    domain: 'myblog.com',
    privateKey: keyPair.privateKey,
    name: 'My Blog',
    contact: '[email protected]'
  });

  // Initialize
  await publisher.initialize();
  console.log('Publisher initialized');

  // Add multiple entries
  const entries = [
    {
      url: 'https://myblog.com/post-1',
      title: 'First Post',
      author: 'John Doe',
      publishedDate: '2024-01-01T00:00:00Z',
      license: { type: 'CC-BY-4.0' }
    },
    {
      url: 'https://myblog.com/post-2',
      title: 'Second Post',
      author: 'Jane Smith',
      publishedDate: '2024-01-02T00:00:00Z',
      license: { type: 'MIT' }
    }
  ];

  for (const entry of entries) {
    const entryId = await publisher.addEntry(entry);
    console.log('Added entry:', entryId);
  }

  // Generate index
  const index = await publisher.generateIndex();
  console.log('Generated index with', index.entries.length, 'entries');

  // Save index to file
  const fs = require('fs');
  fs.writeFileSync('iaindex.json', JSON.stringify(index, null, 2));
}

main().catch(console.error);

Complete Client Example

const { IAIndexClient, CryptoUtils } = require('@iaindex/sdk');

async function main() {
  // Generate or load key pair
  const keyPair = CryptoUtils.generateKeyPair();

  // Create client
  const client = new IAIndexClient({
    clientId: 'my-ai-model',
    privateKey: keyPair.privateKey,
    name: 'My AI Model',
    organization: 'My Company'
  });

  // Initialize
  await client.initialize();
  console.log('Client initialized');

  // Access content
  const url = 'https://example.com/article';
  const content = await client.accessContent(url);
  console.log('Accessed content:', content);

  // Send receipt
  const success = await client.sendReceipt(content, {
    purpose: 'training',
    context: 'pre-training dataset collection',
    datasetId: 'dataset-2024-01',
    modelId: 'my-model-v1.0'
  });

  console.log('Receipt sent:', success);

  // Get verified publishers
  const publishers = await client.getVerifiedPublishers();
  console.log('Verified publishers:', publishers.length);
}

main().catch(console.error);

Environment Variables

You can store your private keys and API configuration in environment variables:

const publisher = new IAIndexPublisher({
  domain: 'yourdomain.com',
  privateKey: process.env.IAINDEX_PRIVATE_KEY,
  name: 'Your Publication',
  contact: process.env.PUBLISHER_CONTACT,
  apiBaseUrl: process.env.IAINDEX_API_URL // optional
});

Error Handling

try {
  await publisher.addEntry(entry);
} catch (error) {
  console.error('Failed to add entry:', error.message);
}

Testing

Run the test suite:

npm test

Run tests with coverage:

npm test -- --coverage

API Base URL

The default API base URL is:

https://aiindex-api.calmmeadow-49a6bfdb.eastus.azurecontainerapps.io

You can override this by passing apiBaseUrl in the constructor options.

License

MIT License - see LICENSE file for details.

Support

• Documentation: https://iaindex.dev/docs
• GitHub: https://github.com/claimtec/iaindex
• Issues: https://github.com/claimtec/iaindex/issues

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.