@oro-ai/sdk 0.6.8

package/README.md

@@ -0,0 +1,206 @@
+# ORO SDK for TypeScript
+
+Official TypeScript SDK for the ORO Bittensor Subnet API.
+
+This SDK is auto-generated from the OpenAPI specification using [@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts).
+
+## Installation
+
+This package is hosted on GitHub Packages. First, configure npm to use GitHub Packages for the `@oro-ai` scope.
+
+**1. Create a GitHub Personal Access Token** with `read:packages` scope at https://github.com/settings/tokens
+
+**2. Add to your project's `.npmrc`:**
+
+```
+@oro-ai:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
+```
+
+Or authenticate via npm login:
+```bash
+npm login --scope=@oro-ai --registry=https://npm.pkg.github.com
+```
+
+**3. Install the package:**
+
+```bash
+npm install @oro-ai/sdk @hey-api/client-fetch
+```
+
+## Quick Start
+
+### Public API (No Auth Required)
+
+```typescript
+import { configurePublicClient, getLeaderboard, getTopAgent } from '@oro-ai/sdk';
+
+// Configure the client
+configurePublicClient('https://api.oro.ai');
+
+// Get leaderboard
+const { data: leaderboard } = await getLeaderboard();
+leaderboard?.entries.forEach(entry => {
+  console.log(`${entry.rank}. ${entry.miner_hotkey}: ${entry.final_score}`);
+});
+
+// Get top agent for emissions
+const { data: top } = await getTopAgent();
+if (top) {
+  console.log(`Top miner: ${top.top_miner_hotkey} with score ${top.top_score}`);
+}
+```
+
+### Authenticated API (Validators/Miners)
+
+Use `configureBittensorAuth` to automatically sign all requests:
+
+```typescript
+import { configureBittensorAuth, claimWork, heartbeat, completeRun } from '@oro-ai/sdk';
+
+// Configure with your wallet's signing function
+configureBittensorAuth('https://api.oro.ai', {
+  hotkey: '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY',
+  sign: (message) => {
+    // Sign the message with your Bittensor wallet
+    // Returns signature as hex string
+    return wallet.sign(message);
+  },
+});
+
+// All requests are now automatically authenticated!
+
+// Validator: Claim work
+const { data: work } = await claimWork();
+if (work) {
+  console.log(`Claimed eval run: ${work.eval_run_id}`);
+
+  // Send heartbeat
+  const { data: hb } = await heartbeat({ path: { eval_run_id: work.eval_run_id } });
+  console.log(`Lease extended to: ${hb?.lease_expires_at}`);
+
+  // Complete run
+  const { data: result } = await completeRun({
+    path: { eval_run_id: work.eval_run_id },
+    body: {
+      terminal_status: 'SUCCESS',
+      validator_score: 0.85,
+    },
+  });
+  console.log(`Completed! Eligible: ${result?.agent_version_became_eligible}`);
+}
+```
+
+### Miner API
+
+```typescript
+import { configureBittensorAuth, submitAgent, getOwnedAgentVersionStatus } from '@oro-ai/sdk';
+
+// Configure auth
+configureBittensorAuth('https://api.oro.ai', {
+  hotkey: minerHotkey,
+  sign: (message) => minerWallet.sign(message),
+});
+
+// Submit an agent
+const file = new File([agentCode], 'agent.py', { type: 'text/x-python' });
+const { data: response } = await submitAgent({
+  body: { file },
+});
+
+if (response?.admission_status === 'ACCEPTED') {
+  console.log(`Submitted! Version ID: ${response.agent_version_id}`);
+
+  // Check status
+  const { data: status } = await getOwnedAgentVersionStatus({
+    path: { agent_version_id: response.agent_version_id },
+  });
+  console.log(`State: ${status?.state}, Score: ${status?.final_score}`);
+}
+```
+
+## Auth Helpers
+
+### `configureBittensorAuth(baseUrl, config)`
+
+Configures the client with automatic Bittensor authentication.
+
+```typescript
+import { configureBittensorAuth } from '@oro-ai/sdk';
+
+configureBittensorAuth('https://api.oro.ai', {
+  hotkey: '5GrwvaEF...',      // Your SS58 hotkey address
+  sign: async (message) => {   // Signs "nonce:timestamp" format
+    return wallet.sign(message);
+  },
+});
+```
+
+### `configurePublicClient(baseUrl)`
+
+Configures the client for public (unauthenticated) endpoints only.
+
+```typescript
+import { configurePublicClient } from '@oro-ai/sdk';
+
+configurePublicClient('https://api.oro.ai');
+```
+
+### `generateAuthHeaders(config, nonce?)`
+
+Generates auth headers manually if needed.
+
+```typescript
+import { generateAuthHeaders } from '@oro-ai/sdk';
+
+const headers = await generateAuthHeaders({
+  hotkey: '5GrwvaEF...',
+  sign: (msg) => wallet.sign(msg),
+});
+// { 'X-Hotkey': '...', 'X-Signature': '...', 'X-Nonce': '...', 'X-Timestamp': '...' }
+```
+
+## API Structure
+
+All SDK functions follow the pattern:
+```typescript
+const { data, error, response } = await functionName({ path?, query?, body? });
+```
+
+- `data` - Parsed response body (typed)
+- `error` - Error object if request failed
+- `response` - Raw fetch Response object
+
+## Development
+
+### Running Tests
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+### Regenerating the SDK
+
+When the API changes:
+
+```bash
+cd packages/typescript
+npm run generate
+```
+
+Or from the repo root:
+
+```bash
+./scripts/generate-typescript.sh
+```
+
+## License
+
+MIT