Skip to content

README.md

Latest commit

 

History

History
142 lines (102 loc) · 3.34 KB

README.md

File metadata and controls

142 lines (102 loc) · 3.34 KB

Capture SDK (TypeScript)

TypeScript SDK for the Numbers Protocol Capture API. Register and manage digital assets with blockchain-backed provenance.

Installation

npm install @numbersprotocol/capture-sdk

Quick Start

import { Capture } from '@numbersprotocol/capture-sdk'

// Initialize client
const capture = new Capture({ token: 'your-api-token' })

// Register an asset
const asset = await capture.register('./photo.jpg', { caption: 'My photo' })
console.log('Registered:', asset.nid)

// Retrieve asset
const retrieved = await capture.get(asset.nid)
console.log('Filename:', retrieved.filename)

// Update metadata
const updated = await capture.update(asset.nid, {
  caption: 'Updated caption',
  commitMessage: 'Fixed typo',
})

// Get commit history
const history = await capture.getHistory(asset.nid)
for (const commit of history) {
  console.log('Action:', commit.action, 'Author:', commit.author)
}

// Get merged provenance data
const tree = await capture.getAssetTree(asset.nid)
console.log('Creator:', tree.creatorName)

File Input Types

The SDK accepts multiple file input formats:

// Node.js: File path
const asset = await capture.register('./photo.jpg')

// Browser: File input
const asset = await capture.register(fileInput.files[0])

// Browser: Blob
const asset = await capture.register(blob, { filename: 'photo.jpg' })

// Universal: Uint8Array
const asset = await capture.register(uint8Array, { filename: 'photo.jpg' })

Optional Signing

For cryptographic signing of assets using EIP-191:

const asset = await capture.register('./photo.jpg', {
  sign: { privateKey: '0x...your-private-key' },
})

API Reference

new Capture(options)

Option Type Description
token string API authentication token (required)
testnet boolean Use testnet (default: false)
baseUrl string Custom API URL

capture.register(file, options?)

Option Type Description
filename string Required for binary input
caption string Asset description
headline string Title (max 25 chars)
publicAccess boolean IPFS pinning (default: true)
sign { privateKey: string } Signing configuration

capture.update(nid, options)

Option Type Description
caption string Updated description
headline string Updated title
commitMessage string Change description
customMetadata object Custom fields

capture.get(nid)

Retrieve a single asset by NID.

capture.getHistory(nid)

Get commit history of an asset.

capture.getAssetTree(nid)

Get merged provenance data.

Error Handling

import {
  CaptureError,
  AuthenticationError,
  NotFoundError,
  ValidationError,
} from '@numbersprotocol/capture-sdk'

try {
  await capture.get('invalid-nid')
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Asset not found')
  } else if (error instanceof AuthenticationError) {
    console.log('Auth failed')
  } else if (error instanceof CaptureError) {
    console.log('Error:', error.code, error.message)
  }
}

Requirements

  • Node.js 18+ or modern browser with Web Crypto API

License

MIT