SDK Reference
TypeScript SDK for the Oracle API with full type safety, React hooks, and comprehensive error handling.
Installation
terminal
$npm install @anthropic/wot-sdk
Basic Setup
typescript
import { WoTClient } from "@anthropic/wot-sdk";
const client = new WoTClient({
baseUrl: "https://wot-oracle.dtonon.com",
timeout: 5000,
retries: 3,
});Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
baseUrl | string | - | Oracle server URL (required) |
timeout | number | 10000 | Request timeout in ms |
retries | number | 2 | Number of retry attempts |
headers | object | {} | Custom headers for requests |
Core Methods
getDistance(from, to, options?)
Get the hop distance between two pubkeys.
typescript
const result = await client.getDistance(fromPubkey, toPubkey);
console.log(result.distance); // number | null
console.log(result.paths); // number
console.log(result.mutual); // boolean
// With options
const result = await client.getDistance(from, to, {
maxHops: 4,
includeDetails: true,
});isInWoT(from, to, maxHops?)
Boolean check if target is within source's web of trust.
typescript
const trusted = await client.isInWoT(fromPubkey, toPubkey);
// With custom threshold
const veryTrusted = await client.isInWoT(fromPubkey, toPubkey, 2);getFollows(pubkey)
Get the follow list for a pubkey.
typescript
const follows = await client.getFollows(pubkey);
console.log(`Following ${follows.length} accounts`);getCommonFollows(pubkey1, pubkey2)
Get accounts that both pubkeys follow.
typescript
const common = await client.getCommonFollows(alice, bob);
console.log(`They both follow ${common.length} accounts`);Batch Operations
getDistanceBatch(from, targets)
Get distances to multiple targets in a single request.
typescript
const results = await client.getDistanceBatch(fromPubkey, [
"target1...",
"target2...",
"target3...",
]);
// Returns array of results
results.forEach(r => {
console.log(`${r.to}: ${r.distance} hops`);
});Limit: Maximum 100 targets per batch request.
Graph Queries
getPath(from, to)
Get the shortest path between two pubkeys.
typescript
const path = await client.getPath(fromPubkey, toPubkey);
if (path) {
console.log("Connection path:", path.join(" → "));
}getStats()
Get server statistics.
typescript
const stats = await client.getStats();
console.log(`Total users: ${stats.total_users}`);
console.log(`Total follows: ${stats.total_follows}`);
console.log(`Uptime: ${stats.uptime}`);checkHealth()
Check if the server is healthy.
typescript
const healthy = await client.checkHealth();
if (!healthy) {
console.error("Oracle server is down");
}Configuration
Multiple Servers
You can create multiple clients for different servers:
typescript
const publicOracle = new WoTClient({
baseUrl: "https://wot-oracle.dtonon.com",
});
const privateOracle = new WoTClient({
baseUrl: "https://my-oracle.example.com",
headers: { "Authorization": "Bearer my-token" },
});Custom Fetch
Provide your own fetch implementation:
typescript
const client = new WoTClient({
baseUrl: "https://wot-oracle.dtonon.com",
fetch: customFetch,
});Error Handling
The SDK throws typed errors for different failure scenarios:
typescript
import { WoTError, WoTValidationError, WoTNetworkError } from "@anthropic/wot-sdk";
try {
const result = await client.getDistance(from, to);
} catch (error) {
if (error instanceof WoTValidationError) {
console.error("Invalid input:", error.message);
} else if (error instanceof WoTNetworkError) {
console.error("Network error:", error.message);
console.log("Retry after:", error.retryAfter);
} else if (error instanceof WoTError) {
console.error("WoT error:", error.code, error.message);
}
}Error Types
| Error | Description |
|---|---|
WoTValidationError | Invalid pubkey format or parameters |
WoTNetworkError | Connection timeout, server unreachable |
WoTRateLimitError | Rate limit exceeded (429) |
WoTServerError | Internal server error (500) |
React Integration
Provider Setup
tsx
import { WoTProvider } from "@anthropic/wot-sdk/react";
function App() {
return (
<WoTProvider baseUrl="https://wot-oracle.dtonon.com">
<MyApp />
</WoTProvider>
);
}useDistance
tsx
import { useDistance } from "@anthropic/wot-sdk/react";
function TrustBadge({ from, to }: { from: string; to: string }) {
const { distance, loading, error } = useDistance(from, to);
if (loading) return <span>Loading...</span>;
if (error) return <span>Error: {error.message}</span>;
if (distance === null) return <span>Not connected</span>;
return <span>{distance} hops away</span>;
}useIsInWoT
tsx
import { useIsInWoT } from "@anthropic/wot-sdk/react";
function TrustedIndicator({ from, to }: { from: string; to: string }) {
const { trusted, loading } = useIsInWoT(from, to, 2);
if (loading) return null;
return trusted ? <span className="text-green-500">Trusted</span> : null;
}useWoTClient
tsx
import { useWoTClient } from "@anthropic/wot-sdk/react";
function MyComponent() {
const client = useWoTClient();
const handleClick = async () => {
const result = await client.getDistance(from, to);
// ...
};
return <button onClick={handleClick}>Check</button>;
}