npm package: @neuranetnetwork/sdk
Description: Official JavaScript/TypeScript SDK for NeuraNET - Decentralized GPU Compute Network
Author: NeuraNETNetwork
Latest version: 1.0.1

# @neuranetnetwork/sdk

[![npm version](https://img.shields.io/npm/v/@neuranetnetwork/sdk.svg)](https://www.npmjs.com/package/@neuranetnetwork/sdk)
[![npm downloads](https://img.shields.io/npm/dm/@neuranetnetwork/sdk.svg)](https://www.npmjs.com/package/@neuranetnetwork/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official JavaScript/TypeScript SDK for NeuraNET - Decentralized GPU Compute Network

📦 **NPM Package**: [https://www.npmjs.com/package/@neuranetnetwork/sdk](https://www.npmjs.com/package/@neuranetnetwork/sdk)

## Installation

```bash
npm install @neuranetnetwork/sdk
# or
yarn add @neuranetnetwork/sdk
# or
pnpm add @neuranetnetwork/sdk
```

## Quick Start

### Using API Key (Recommended for servers)

```typescript
import { NeuraNET } from '@neuranetnetwork/sdk';

const client = new NeuraNET({
  apiKey: 'nn_live_xxxxxxxxxxxxx', // Get from /api/keys
  apiUrl: 'https://api.neuranet.network'
});

// Set your wallet address
client.setWalletAddress('YourSolanaWalletAddress');

// Create a job using prepaid credits
const job = await client.createJob({
  model: 'llama2-7b',
  prompt: 'Write a short story about a robot learning to paint',
  maxTokens: 1000,
  paymentAmount: 0.05 // SOL
});

console.log('Job created:', job.jobId);

// Wait for the result
const result = await client.waitForJob(job.jobId);
console.log('Result:', result.result);
```

### Using Webhooks (For async workflows)

```typescript
const job = await client.createJob({
  model: 'mistral-7b',
  prompt: 'Summarize this article: ...',
  paymentAmount: 0.03,
  callbackUrl: 'https://myapp.com/webhooks/neuranet',
  callbackHeaders: {
    'Authorization': 'Bearer my-webhook-secret'
  }
});

// Result will be POSTed to your webhook URL when complete
console.log('Job submitted:', job.jobId);
```

### Real-time Streaming

```typescript
// Stream job updates as they happen
const cleanup = client.streamJob(job.jobId, (event) => {
  switch (event.event) {
    case 'job:status':
      console.log('Status:', event.data.status);
      break;
    case 'job:progress':
      console.log('Progress:', event.data.partialResult);
      break;
    case 'job:complete':
      console.log('Done!', event.data.result);
      break;
    case 'job:error':
      console.error('Error:', event.data.error);
      break;
  }
});

// Call cleanup() to stop streaming
```

## Features

### Credit Management

```typescript
// Check your credit balance
const balance = await client.getCreditBalance();
console.log('Balance:', balance.balance, 'SOL');

// Get deposit instructions
const info = await client.getDepositInfo();
console.log('Send SOL to:', info.platformWallet);

// After sending SOL, deposit credits
await client.depositCredits(0.5, 'your-tx-signature');

// View transaction history
const history = await client.getCreditTransactions(20);
```

### Browse Available Resources

```typescript
// List available AI models
const models = await client.listModels();
console.log('Models:', models);

// List GPU nodes
const nodes = await client.listNodes({ status: 'online', minVRAM: 8 });
console.log('Nodes:', nodes.items);
```

### Direct Solana Payment

For cases where you want to pay per-job instead of using credits:

```typescript
import { Connection, PublicKey, SystemProgram, Transaction } from '@solana/web3.js';

// 1. Get platform wallet
const paymentInfo = await client.getPaymentInfo();

// 2. Send SOL payment (using your wallet)
const connection = new Connection('https://api.mainnet-beta.solana.com');
const tx = new Transaction().add(
  SystemProgram.transfer({
    fromPubkey: yourWallet,
    toPubkey: new PublicKey(paymentInfo.platformWallet),
    lamports: 0.05 * 1e9 // 0.05 SOL
  })
);
const signature = await sendTransaction(tx, connection);

// 3. Create job with transaction signature
const job = await client.createJobWithTransaction({
  model: 'llama2-7b',
  prompt: 'Your prompt',
  paymentAmount: 0.05,
  txSignature: signature
});
```

## API Reference

### `NeuraNET(config?)`

Create a new client instance.

```typescript
interface NeuraNETConfig {
  apiUrl?: string;    // API base URL (default: https://api.neuranet.network)
  apiKey?: string;    // Your API key (get from POST /api/keys)
  timeout?: number;   // Request timeout in ms (default: 30000)
}
```

### Jobs

| Method | Description |
|--------|-------------|
| `createJob(options)` | Create job using credits |
| `createJobWithTransaction(options)` | Create job with Solana tx |
| `getJob(jobId)` | Get job details |
| `listJobs(options?)` | List jobs with filters |
| `waitForJob(jobId, options?)` | Poll until job completes |
| `streamJob(jobId, onEvent)` | Stream job updates via SSE |

### Nodes

| Method | Description |
|--------|-------------|
| `listNodes(options?)` | List GPU nodes |
| `listModels()` | Get available AI models |

### Credits

| Method | Description |
|--------|-------------|
| `getCreditBalance()` | Get your credit balance |
| `depositCredits(amount, txSignature)` | Deposit SOL as credits |
| `getCreditTransactions(limit?)` | Get transaction history |
| `getDepositInfo()` | Get deposit instructions |

### System

| Method | Description |
|--------|-------------|
| `getPaymentInfo()` | Get platform payment info |
| `healthCheck()` | Check API health |

## Error Handling

```typescript
import { NeuraNETError } from '@neuranetnetwork/sdk';

try {
  const job = await client.createJob({ /* ... */ });
} catch (error) {
  if (error instanceof NeuraNETError) {
    console.error('Code:', error.code);
    console.error('Message:', error.message);
    
    // Handle specific errors
    if (error.code === 'PAY_006') {
      console.log('Insufficient credits - please deposit more SOL');
    }
  }
}
```

## TypeScript Support

Full TypeScript support with exported types:

```typescript
import type { 
  Job, 
  GPUNode, 
  CreateJobOptions,
  CreditBalance,
  JobStreamEvent 
} from '@neuranetnetwork/sdk';
```

## License

MIT