@stacknet/stacks 0.1.0

package/src/clients/network.ts

@@ -0,0 +1,118 @@
+/**
+ * Network Client
+ * Network status, MPC nodes, consensus, and auth metrics
+ */
+
+import { DEFAULT_GLAYER_NETWORK_URL, JSON_HEADERS } from '../utils/constants';
+import { StacksSDKError } from '../utils/errors';
+import type {
+  NetworkStatus,
+  MPCNode,
+  ConsensusStatus,
+  LeaderStatus,
+  AuthMetrics,
+  NetworkClientConfig,
+} from '../types/network';
+
+export type { NetworkClientConfig } from '../types/network';
+
+const API_PATH = '/api/v2';
+
+export class NetworkClient {
+  private baseUrl: string;
+  private authToken: string | null;
+
+  constructor(config: NetworkClientConfig = {}) {
+    this.baseUrl = config.baseUrl || DEFAULT_GLAYER_NETWORK_URL;
+    this.authToken = config.authToken || null;
+  }
+
+  setAuthToken(token: string | null) {
+    this.authToken = token;
+  }
+
+  private get headers(): Record<string, string> {
+    const h: Record<string, string> = { ...JSON_HEADERS };
+    if (this.authToken) {
+      h['Authorization'] = `Bearer ${this.authToken}`;
+    }
+    return h;
+  }
+
+  private async request<T>(method: string, url: string): Promise<T> {
+    const response = await fetch(url, { method, headers: this.headers });
+
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}));
+      throw new StacksSDKError(
+        'bad_request:api',
+        data.error?.message || `Request failed: ${response.statusText}`
+      );
+    }
+
+    const data = await response.json();
+    return (data && typeof data === 'object' && 'data' in data) ? data.data : data;
+  }
+
+  // =========================================================================
+  // Health
+  // =========================================================================
+
+  async checkHealth(): Promise<boolean> {
+    try {
+      const response = await fetch(`${this.baseUrl}/health`);
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  // =========================================================================
+  // Network
+  // =========================================================================
+
+  async getNetworkStatus(): Promise<NetworkStatus> {
+    return this.request<NetworkStatus>('GET', `${this.baseUrl}${API_PATH}/network/status`);
+  }
+
+  async getMPCNodes(): Promise<MPCNode[]> {
+    return this.request<MPCNode[]>('GET', `${this.baseUrl}${API_PATH}/network/nodes`);
+  }
+
+  async getNodeHealth(nodeId: string): Promise<{ healthy: boolean; latency_ms: number }> {
+    return this.request('GET', `${this.baseUrl}${API_PATH}/network/nodes/${nodeId}/health`);
+  }
+
+  // =========================================================================
+  // Consensus
+  // =========================================================================
+
+  async getConsensusStatus(): Promise<ConsensusStatus> {
+    return this.request<ConsensusStatus>('GET', `${this.baseUrl}/consensus/status`);
+  }
+
+  async getLeaderStatus(): Promise<LeaderStatus> {
+    return this.request<LeaderStatus>('GET', `${this.baseUrl}/consensus/leader`);
+  }
+
+  // =========================================================================
+  // Metrics
+  // =========================================================================
+
+  async getAuthMetrics(stackId?: string): Promise<AuthMetrics> {
+    const path = stackId ? `/stacks/${stackId}/metrics` : '/metrics';
+    return this.request<AuthMetrics>('GET', `${this.baseUrl}${API_PATH}${path}`);
+  }
+}
+
+/**
+ * Create a NetworkClient instance
+ */
+export function createNetworkClient(config: NetworkClientConfig = {}): NetworkClient {
+  return new NetworkClient(config);
+}
+
+/**
+ * Default network client instance
+ */
+export const networkClient = createNetworkClient();

package/src/clients/points.ts

@@ -0,0 +1,403 @@
+/**
+ * Points Client
+ *
+ * Client for interacting with the Points Coprocessor API.
+ * Provides access to the internal reward and reputation framework for StackNet.
+ */
+
+import { DEFAULT_MAGMA_RPC_URL, JSON_HEADERS } from '../utils/constants';
+import { StacksSDKError } from '../utils/errors';
+import type {
+  ContextDomain,
+  PointContext,
+  Delegation,
+  PointBalance,
+  PointRecord,
+  CreateDomainInput,
+  CreateContextInput,
+  CreateDelegationInput,
+  AddPointsInput,
+  SpendPointsInput,
+  HistoryFilters,
+  DelegationFilters,
+  DomainsListResponse,
+  DomainResponse,
+  ContextsListResponse,
+  ContextResponse,
+  DelegationsListResponse,
+  DelegationResponse,
+  PointRecordResponse,
+  PointSpendResponse,
+  HistoryResponse,
+  InitNetworkResponse,
+  PaymentRequiredResponse,
+  PointsClientConfig,
+} from '../types/points';
+
+export type { PointsClientConfig };
+
+export class PointsClient {
+  private baseUrl: string;
+
+  constructor(config: PointsClientConfig = {}) {
+    this.baseUrl = config.baseUrl || DEFAULT_MAGMA_RPC_URL;
+  }
+
+  private get pointsUrl(): string {
+    return `${this.baseUrl}/cpx/points`;
+  }
+
+  // ============================================================================
+  // Network Initialization
+  // ============================================================================
+
+  /**
+   * Initialize the default geoffnet domain and contexts.
+   * Should only be called once during network bootstrap.
+   */
+  async initNetworkDomain(): Promise<InitNetworkResponse> {
+    const response = await fetch(`${this.pointsUrl}/init`, {
+      method: 'POST',
+      headers: JSON_HEADERS,
+    });
+
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}));
+      throw new StacksSDKError(
+        'bad_request:api',
+        data.error || `Failed to initialize network domain: ${response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+
+  // ============================================================================
+  // Domain Operations
+  // ============================================================================
+
+  /**
+   * List all context domains
+   */
+  async listDomains(): Promise<DomainsListResponse> {
+    const response = await fetch(`${this.pointsUrl}/domains`);
+
+    if (!response.ok) {
+      throw new StacksSDKError(
+        'bad_request:api',
+        `Failed to list domains: ${response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Get a domain by ID
+   */
+  async getDomain(domainId: string): Promise<ContextDomain | null> {
+    const response = await fetch(`${this.pointsUrl}/domains/${domainId}`);
+
+    if (response.status === 404) {
+      return null;
+    }
+
+    if (!response.ok) {
+      throw new StacksSDKError(
+        'bad_request:api',
+        `Failed to get domain: ${response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Create a new context domain.
+   * Note: Requires 402 payment for non-default domains.
+   */
+  async createDomain(input: CreateDomainInput): Promise<DomainResponse> {
+    const response = await fetch(`${this.pointsUrl}/domains`, {
+      method: 'POST',
+      headers: JSON_HEADERS,
+      body: JSON.stringify(input),
+    });
+
+    // Handle 402 Payment Required
+    if (response.status === 402) {
+      const data: PaymentRequiredResponse = await response.json();
+      throw new StacksSDKError(
+        'payment_required:api',
+        `${data.error}${data.paymentDetails ? ` (Payment: ${JSON.stringify(data.paymentDetails)})` : ''}`
+      );
+    }
+
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}));
+      throw new StacksSDKError(
+        'bad_request:api',
+        data.error || `Failed to create domain: ${response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+
+  // ============================================================================
+  // Context Operations
+  // ============================================================================
+
+  /**
+   * List all point contexts, optionally filtered by domain
+   */
+  async listContexts(domainId?: string): Promise<ContextsListResponse> {
+    const params = domainId ? `?domainId=${domainId}` : '';
+    const response = await fetch(`${this.pointsUrl}/contexts${params}`);
+
+    if (!response.ok) {
+      throw new StacksSDKError(
+        'bad_request:api',
+        `Failed to list contexts: ${response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Get a context by ID
+   */
+  async getContext(contextId: string): Promise<PointContext | null> {
+    const response = await fetch(`${this.pointsUrl}/contexts/${contextId}`);
+
+    if (response.status === 404) {
+      return null;
+    }
+
+    if (!response.ok) {
+      throw new StacksSDKError(
+        'bad_request:api',
+        `Failed to get context: ${response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Create a new point context.
+   * Note: Requires 402 payment for non-default contexts.
+   */
+  async createContext(input: CreateContextInput): Promise<ContextResponse> {
+    const response = await fetch(`${this.pointsUrl}/contexts`, {
+      method: 'POST',
+      headers: JSON_HEADERS,
+      body: JSON.stringify(input),
+    });
+
+    // Handle 402 Payment Required
+    if (response.status === 402) {
+      const data: PaymentRequiredResponse = await response.json();
+      throw new StacksSDKError(
+        'payment_required:api',
+        `${data.error}${data.paymentDetails ? ` (Payment: ${JSON.stringify(data.paymentDetails)})` : ''}`
+      );
+    }
+
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}));
+      throw new StacksSDKError(
+        'bad_request:api',
+        data.error || `Failed to create context: ${response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+
+  // ============================================================================
+  // Delegation Operations
+  // ============================================================================
+
+  /**
+   * List delegations with optional filters
+   */
+  async listDelegations(filters: DelegationFilters = {}): Promise<DelegationsListResponse> {
+    const params = new URLSearchParams();
+    if (filters.domainId) params.set('domainId', filters.domainId);
+    if (filters.delegator) params.set('delegator', filters.delegator);
+    if (filters.delegate) params.set('delegate', filters.delegate);
+    if (filters.activeOnly) params.set('activeOnly', 'true');
+
+    const queryString = params.toString();
+    const url = `${this.pointsUrl}/delegations${queryString ? `?${queryString}` : ''}`;
+
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      throw new StacksSDKError(
+        'bad_request:api',
+        `Failed to list delegations: ${response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Create a new delegation
+   */
+  async createDelegation(input: CreateDelegationInput): Promise<DelegationResponse> {
+    const response = await fetch(`${this.pointsUrl}/delegations`, {
+      method: 'POST',
+      headers: JSON_HEADERS,
+      body: JSON.stringify(input),
+    });
+
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}));
+      throw new StacksSDKError(
+        'bad_request:api',
+        data.error || `Failed to create delegation: ${response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Revoke a delegation
+   */
+  async revokeDelegation(delegationId: string): Promise<{ success: boolean }> {
+    const response = await fetch(`${this.pointsUrl}/delegations/${delegationId}`, {
+      method: 'DELETE',
+    });
+
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}));
+      throw new StacksSDKError(
+        'bad_request:api',
+        data.error || `Failed to revoke delegation: ${response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+
+  // ============================================================================
+  // Points Operations
+  // ============================================================================
+
+  /**
+   * Add points (positive or negative) to an MID
+   */
+  async addPoints(input: AddPointsInput): Promise<PointRecordResponse> {
+    const response = await fetch(`${this.pointsUrl}/add`, {
+      method: 'POST',
+      headers: JSON_HEADERS,
+      body: JSON.stringify(input),
+    });
+
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}));
+      throw new StacksSDKError(
+        'bad_request:api',
+        data.error || `Failed to add points: ${response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Spend points (settlement via MetaChain)
+   */
+  async spendPoints(input: SpendPointsInput): Promise<PointSpendResponse> {
+    const response = await fetch(`${this.pointsUrl}/spend`, {
+      method: 'POST',
+      headers: JSON_HEADERS,
+      body: JSON.stringify(input),
+    });
+
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}));
+      throw new StacksSDKError(
+        'bad_request:api',
+        data.error || `Failed to spend points: ${response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Get points balance for an MID
+   */
+  async getBalance(
+    mid: string,
+    options: { domainId?: string; contextId?: string } = {}
+  ): Promise<PointBalance> {
+    const params = new URLSearchParams();
+    if (options.domainId) params.set('domainId', options.domainId);
+    if (options.contextId) params.set('contextId', options.contextId);
+
+    const queryString = params.toString();
+    const url = `${this.pointsUrl}/balance/${mid}${queryString ? `?${queryString}` : ''}`;
+
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      throw new StacksSDKError(
+        'bad_request:api',
+        `Failed to get balance: ${response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Get points history with optional filters
+   */
+  async getHistory(filters: HistoryFilters = {}): Promise<HistoryResponse> {
+    const params = new URLSearchParams();
+    if (filters.mid) params.set('mid', filters.mid);
+    if (filters.domainId) params.set('domainId', filters.domainId);
+    if (filters.contextId) params.set('contextId', filters.contextId);
+    if (filters.periodStart) params.set('periodStart', filters.periodStart.toString());
+    if (filters.periodEnd) params.set('periodEnd', filters.periodEnd.toString());
+    if (filters.taskId) params.set('taskId', filters.taskId);
+    if (filters.limit) params.set('limit', filters.limit.toString());
+    if (filters.offset) params.set('offset', filters.offset.toString());
+
+    const queryString = params.toString();
+    const url = `${this.pointsUrl}/history${queryString ? `?${queryString}` : ''}`;
+
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      throw new StacksSDKError(
+        'bad_request:api',
+        `Failed to get history: ${response.statusText}`
+      );
+    }
+
+    return response.json();
+  }
+}
+
+// ============================================================================
+// Factory Functions
+// ============================================================================
+
+/**
+ * Create a PointsClient instance
+ */
+export function createPointsClient(config: PointsClientConfig = {}): PointsClient {
+  return new PointsClient(config);
+}
+
+/**
+ * Default points client instance
+ */
+export const pointsClient = createPointsClient();