@noves/intent-typescript-sdk/README.md

Noves Intent Typescript SDK

# Noves Intent TypeScript SDK

The official TypeScript SDK for interacting with Noves Intents, providing seamless access to blockchain data and analytics.

## Features

- 🎯 Intent-based data querying
- 🔄 Real-time data streaming
- 🔒 Type-safe API
- ⚡ Optimized for both client and server environments
- 🌐 Cross-chain support

## Installation

```bash
npm install @noves/intent-ts-sdk
```

## Quick Start

```typescript
import { ClientSideIntentSDK } from "@noves/intent-typescript-sdk";
const sdk = new ClientSideIntentSDK();
// Get available intents
const intents = await sdk.getIntents();
console.log(intents);
```

## Client-Side Usage

The client-side SDK is optimized for browser environments and uses WebSocket for streaming data.

```typescript
import { ClientSideIntentSDK } from "@noves/intent-typescript-sdk";
const sdk = new ClientSideIntentSDK();
// Get a single value
const data = await sdk.getValue("token-price-history", {
  chain: "ethereum",
  token_address: "0x..."
});
// Stream real-time data
sdk.getStream(
  "token-price-ticks",
  {
    chain: "ethereum",
    token_address: "0x..."
  },
  (data) => console.log("New price:", data),
  (error) => console.error("Stream error:", error),
  () => console.log("Stream completed")
);
// Stop streaming
sdk.stopStream("token-price-ticks");
```

## Server-Side Usage

The server-side SDK is optimized for Node.js environments and uses gRPC for streaming data.

```typescript
import { ServerSideIntentSDK } from "@noves/intent-typescript-sdk/server";
const sdk = new ServerSideIntentSDK();
// Get a single value
const data = await sdk.getValue("wallet-view", {
  chain: "avalanche",
  address: "0x..."
});
// Stream data with gRPC
sdk.getStream(
  "live-bridge-txs",
  {},
  (data) => console.log("New bridge transaction:", data),
  (error) => console.error("Stream error:", error),
  () => console.log("Stream completed")
);
// Stop streaming
sdk.stopStream("live-bridge-txs");
```


## Core Methods

### getIntents()
Returns a list of all available intents.

```typescript
const intents = await sdk.getIntents();
```

### getValue(intentId, params, pageSize?)
Executes a value intent and returns the result.

```typescript
const result = await sdk.getValue("intent-id", {
  param1: "value1",
  param2: "value2"
});
```


### getStream(intentId, params, onData, onError?, onComplete?)
Initiates a data stream for the specified intent.

```typescript
sdk.getStream(
  "intent-id",
  { param1: "value1" },
  (data) => console.log(data),
  (error) => console.error(error),
  () => console.log("Stream ended")
);
```


## Type Safety

The SDK provides full TypeScript support with auto-generated types for all intents and their parameters.

```typescript
import { ValueIntentId, StreamableIntentId } from "@noves/intent-typescript-sdk";
// Type-safe intent IDs
const valueIntent: ValueIntentId = "token-price-history";
const streamIntent: StreamableIntentId = "token-price-ticks";
```


## Error Handling

The SDK handles errors gracefully with proper error types and messages.
```typescript
import { IntentSDKError } from "@noves/intent-typescript-sdk";
try {
  await sdk.getValue("non-existent-intent");
} catch (error) {
  if (error instanceof IntentSDKError) {
    console.error("SDK Error:", error.message);
  }
}
```


## Support

Feel free to join our [Telegram community](https://t.me/+tsK4RSu0Q1VjNzVh) to get help or feedback.