@spacecomputer-io/orbitport-sdk-ts

v0.0.4

Published

a month ago

Official TypeScript SDK for SpaceComputer Orbitport

Orbitport SDK

Official TypeScript SDK for SpaceComputer Orbitport - providing access to cosmic True Random Number Generator (cTRNG) services.

Installation

npm i @spacecomputer-io/orbitport-sdk-ts

Quick Start

import { OrbitportSDK } from "@spacecomputer/orbitport-sdk";

// With API credentials (tries API first, falls back to IPFS)
const sdkWithAPI = new OrbitportSDK({
  config: {
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
  },
});
const resultWithAPI = await sdkWithAPI.ctrng.random();
console.log(resultWithAPI.data.data);

// Without API credentials (uses IPFS only)
const sdkIPFSOnly = new OrbitportSDK({ config: {} });
const resultIPFSOnly = await sdkIPFSOnly.ctrng.random();
console.log(resultIPFSOnly.data.data);

Features

🌌 Cosmic True Random Number Generation - Access space-based randomness via API or IPFS.
🛰️ IPFS Beacon Support - Fallback to decentralized IPFS beacons for cTRNG data.
🔄 Automatic Fallback - Defaults to API if credentials are provided, with automatic fallback to IPFS.
🔐 Secure Authentication - Built-in token management with automatic refresh for API access.
비교 Source Comparison - Always reads from both IPFS gateway and API to ensure data integrity, just like beacon.js.
💾 Flexible Storage - Works in browser, Node.js, and custom environments.
📦 TypeScript First - Full type safety and IntelliSense support.
🛡️ Production Ready - Comprehensive error handling and validation.

API Reference

Configuration

The SDK can be initialized with or without API credentials.

interface OrbitportConfig {
  clientId?: string; // Optional: Your client ID
  clientSecret?: string; // Optional: Your client secret
  authUrl?: string; // Optional: Auth server URL
  apiUrl?: string; // Optional: API server URL
  timeout?: number; // Optional: Request timeout in ms (default: 30000)
  retryAttempts?: number; // Optional: Retry attempts (default: 3)
  retryDelay?: number; // Optional: Retry delay in ms (default: 1000)
  ipfs?: IPFSConfig; // Optional: Custom IPFS settings
}

interface IPFSConfig {
  gateway?: string;
  apiUrl?: string;
  timeout?: number;
  defaultBeaconPath?: string;
}

cTRNG Service (`sdk.ctrng`)

`random(request?, options?)`

Generates true random numbers from the best available source.

Behavior:

If clientId and clientSecret are provided, it attempts to use the API first. If the API call fails, it automatically falls back to IPFS.
If credentials are not provided, it uses IPFS by default.
When using IPFS, it always fetches from both the gateway and the API node to compare results for integrity, exactly like the original beacon.js script.

// Automatic source selection (API if configured, otherwise IPFS)
const result = await sdk.ctrng.random();

// Force use of IPFS beacon
const ipfsResult = await sdk.ctrng.random({ src: "ipfs" });

// Force use of a specific API source (if configured)
const rngResult = await sdk.ctrng.random({ src: "rng" });

// Use a custom IPFS beacon path
const customBeaconResult = await sdk.ctrng.random({
  src: "ipfs",
  beaconPath: "/ipns/your-custom-beacon-cid",
});

// Select a specific cTRNG value from the beacon array
const specificValue = await sdk.ctrng.random({
  src: "ipfs",
  index: 2, // Select the 3rd value (0-indexed)
});

// Get cTRNG from a specific block (traverse back through the chain)
const blockValue = await sdk.ctrng.random({
  src: "ipfs",
  block: 10012, // Get from block 10012
  index: 1, // Select the 2nd value from that block
});

// Get latest block with specific index
const latestValue = await sdk.ctrng.random({
  src: "ipfs",
  block: "INF", // Latest block (default)
  index: 0, // First value (default)
});

Response Structure

All random() calls return a consistent response structure:

interface ServiceResult<CTRNGResponse> {
  data: CTRNGResponse;
  metadata: {
    timestamp: number;
    request_id?: string;
  };
  success: boolean;
}

interface CTRNGResponse {
  service: string; // "trng", "rng", or "ipfs-beacon"
  src: string; // "trng", "rng", or "ipfs"
  data: string; // The random value as a string
  signature?: {
    value: string;
    pk: string;
  }; // API only
  timestamp?: string;
  provider?: string;
}

Authentication (`sdk.auth`)

Authentication methods are only relevant when using the API.

// Check if token is valid
const isValid = await sdk.auth.isTokenValid();

// Get token information
const tokenInfo = await sdk.auth.getTokenInfo();

Error Handling

The SDK provides comprehensive error handling with specific error types:

import { OrbitportSDKError, ERROR_CODES } from "@spacecomputer/orbitport-sdk";

try {
  const result = await sdk.ctrng.random();
} catch (error) {
  if (error instanceof OrbitportSDKError) {
    console.log("Error code:", error.code); // e.g., AUTH_FAILED, NETWORK_ERROR
    console.log("Error message:", error.message);
  }
}

IPFS Beacon Integration Details

The SDK's IPFS integration is designed to mirror the functionality of the beacon.js script, providing robustness and verifiability.

Default IPFS Configuration

Gateway: https://ipfs.io
API: https://ipfs.io
Default Beacon: /ipns/k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f

You can override these defaults in the SDK configuration.

Debug Output

When debug: true is enabled, you will see detailed logs, including the IPFS source comparison:

[OrbitportSDK] Reading from BOTH IPFS sources:
  - Gateway: https://ipfs.io
  - API: https://ipfs.io
  - Path: /ipns/k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f

[OrbitportSDK] ✓ Gateway and API agree on sequence/previous

cTRNG Array Selection and Block Traversal

IPFS beacons contain arrays of cTRNG values that are posted in batches. Each beacon also has a "previous" property that links to the previous block, creating a chain. The SDK allows you to:

Select specific values from the cTRNG array using the index parameter
Traverse back through blocks using the block parameter

// Get the first cTRNG value from latest block (default)
const firstValue = await sdk.ctrng.random({ src: "ipfs" });

// Get the second cTRNG value from latest block (index 1)
const secondValue = await sdk.ctrng.random({
  src: "ipfs",
  index: 1,
});

// Get cTRNG from a specific block (traverse back through the chain)
const blockValue = await sdk.ctrng.random({
  src: "ipfs",
  block: 10012, // Get from block 10012
  index: 2, // Select the 3rd value from that block
});

// Get latest block with specific index
const latestValue = await sdk.ctrng.random({
  src: "ipfs",
  block: "INF", // Latest block (default)
  index: 0, // First value (default)
});

Important Notes:

The index parameter is 0-based (first value is index 0)
The block parameter can be:
- "INF" (default) - Get from the latest block
- A number - Traverse back through the chain to that specific block
If the requested index exceeds the array length, it will be automatically adjusted using modulo operation
For example, if the beacon has 3 values and you request index 5, it will return index 2 (5 % 3 = 2)
If the requested block is greater than the current block, an error will be thrown
Block traversal follows the "previous" chain, so requesting block 10012 will check the latest block, then traverse back until it finds block 10012
This prevents out-of-bounds errors and ensures the request never fails
When debug mode is enabled, you'll see detailed logs about block traversal and index adjustments

Development

Prerequisites

Node.js 22+
TypeScript 5.0+

Setup

# Install dependencies
npm install

# Build the project
npm run build

Testing

# Run all tests
npm test

# Run e2e tests (requires valid credentials)
ORBITPORT_CLIENT_ID="your-id" ORBITPORT_CLIENT_SECRET="your-secret" npm run test:e2e

License

MIT License - see LICENSE file for details.

Support

📧 Email: [email protected]
🐛 Issues: GitHub Issues
📖 Docs: SpaceComputer Documentation