@greenhelix/sdk 1.0.7

package/README.md

@@ -0,0 +1,97 @@
+# @greenhelix/sdk
+
+TypeScript SDK for the [A2A Commerce Platform](https://github.com/mirni/a2a) -- agent-to-agent payments, escrow, marketplace, identity, and trust scoring.
+
+## Installation
+
+```bash
+npm install @greenhelix/sdk
+```
+
+Requires Node.js 18+. Zero dependencies (uses built-in `fetch`).
+
+## Quick Start
+
+```typescript
+import { A2AClient } from '@greenhelix/sdk';
+
+const client = new A2AClient({
+  baseUrl: 'https://api.greenhelix.net',
+  apiKey: 'a2a_free_...',
+});
+
+// Health check
+const health = await client.health();
+
+// Get wallet balance
+const balance = await client.getBalance('my-agent');
+
+// Create and capture a payment
+const intent = await client.createPaymentIntent({
+  payer: 'buyer-agent',
+  payee: 'seller-agent',
+  amount: 10.0,
+});
+const settlement = await client.capturePayment(intent.intent_id);
+
+// Search marketplace
+const services = await client.searchServices({ query: 'analytics' });
+```
+
+## Configuration
+
+```typescript
+const client = new A2AClient({
+  baseUrl: 'https://api.greenhelix.net',  // or http://localhost:8000
+  apiKey: 'a2a_free_...',
+  timeout: 30000,          // request timeout (ms)
+  maxRetries: 3,           // automatic retries with backoff
+});
+```
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `health()` | Health check |
+| `getBalance(agentId)` | Wallet balance |
+| `deposit(agentId, amount)` | Add credits |
+| `createPaymentIntent({...})` | Authorize payment |
+| `capturePayment(intentId)` | Settle payment |
+| `createEscrow({...})` | Hold funds in escrow |
+| `releaseEscrow(escrowId)` | Release escrow |
+| `searchServices({query})` | Search marketplace |
+| `bestMatch(query)` | Best service match |
+| `getTrustScore(serverId)` | Trust score |
+| `registerAgent(agentId)` | Create identity |
+| `sendMessage({...})` | Encrypted messaging |
+| `execute(tool, params)` | Generic tool call |
+| `batchExecute(calls)` | Multi-tool batch |
+
+## Error Handling
+
+```typescript
+import { A2AError } from '@greenhelix/sdk';
+
+try {
+  await client.execute('deposit', { agent_id: 'x', amount: 100 });
+} catch (error) {
+  if (error instanceof A2AError) {
+    console.error(`API error: ${error.code} - ${error.message}`);
+    if (error.status === 429) {
+      // Rate limited
+    }
+  }
+}
+```
+
+## Links
+
+- [API Documentation](https://api.greenhelix.net/docs)
+- [Sandbox](https://sandbox.greenhelix.net)
+- [GitHub](https://github.com/mirni/a2a)
+- [SDK Guide](https://github.com/mirni/a2a/blob/main/docs/sdk-guide.md)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,195 @@
+/**
+ * A2A Commerce Gateway — TypeScript SDK Client.
+ *
+ * Zero-dependency client using native fetch (Node 18+).
+ *
+ * @example
+ * ```ts
+ * const client = new A2AClient({ apiKey: "ak_pro_..." });
+ * const health = await client.health();
+ * const balance = await client.getBalance("my-agent");
+ * ```
+ */
+import type { A2AClientOptions, AgentIdentityResponse, ApiKeyResponse, BalanceResponse, CheckoutResult, EscrowResponse, EventListResponse, EventPublishResponse, ExecuteResponse, HealthResponse, KeyRotationResponse, MessageListResponse, MetricsSubmissionResponse, NegotiationResponse, OrgDetailResponse, OrgMemberResponse, OrgResponse, PaymentHistoryResponse, PaymentIntent, RefundResponse, ServerSearchResponse, ServiceDetailResponse, ServiceRatingResponse, ServiceRegistrationResponse, SubscriptionDetailResponse, SubscriptionListResponse, SubscriptionResponse, ToolPricing, TrustScore, UsageSummaryResponse, VerifiedClaimsResponse, VerifyAgentResponse, WebhookDeleteResponse, WebhookListResponse, WebhookResponse } from "./types";
+export declare class A2AClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly retryBaseDelay;
+    private readonly pricingCacheTtl;
+    private pricingCache;
+    private pricingCacheTime;
+    constructor(options?: A2AClientOptions);
+    private headers;
+    private request;
+    /**
+     * Internal helper for REST endpoint calls with auth and error handling.
+     */
+    private rest;
+    /** GET /v1/health */
+    health(): Promise<HealthResponse>;
+    /** GET /v1/pricing — full catalog (cached). */
+    pricing(useCache?: boolean): Promise<ToolPricing[]>;
+    /** GET /v1/pricing/:tool — single tool pricing. */
+    pricingTool(toolName: string): Promise<ToolPricing>;
+    /** POST /v1/execute — execute a tool. */
+    execute(tool: string, params?: Record<string, any>): Promise<ExecuteResponse>;
+    /** POST /v1/checkout — create a Stripe Checkout session. */
+    checkout(options: {
+        package?: string;
+        credits?: number;
+        successUrl?: string;
+        cancelUrl?: string;
+    }): Promise<CheckoutResult>;
+    /** Clear the pricing cache. */
+    invalidatePricingCache(): void;
+    /** Get wallet balance for an agent. */
+    getBalance(agentId: string): Promise<BalanceResponse>;
+    /** Deposit credits into a wallet. Returns new balance. */
+    deposit(agentId: string, amount: number, description?: string): Promise<number>;
+    /** Get usage summary for an agent. */
+    getUsageSummary(agentId: string, since?: number): Promise<UsageSummaryResponse>;
+    /** Create a payment intent. */
+    createPaymentIntent(payer: string, payee: string, amount: number, description?: string, idempotencyKey?: string): Promise<PaymentIntent>;
+    /** Capture a pending payment intent. */
+    capturePayment(intentId: string): Promise<PaymentIntent>;
+    /** Create an escrow. */
+    createEscrow(payer: string, payee: string, amount: number, description?: string, timeoutHours?: number): Promise<EscrowResponse>;
+    /** Release an escrow to the payee. */
+    releaseEscrow(escrowId: string): Promise<EscrowResponse>;
+    /** Search the marketplace. */
+    searchServices(options?: {
+        query?: string;
+        category?: string;
+        tags?: string[];
+        maxCost?: number;
+        limit?: number;
+    }): Promise<Record<string, any>[]>;
+    /** Find best matching services. */
+    bestMatch(query: string, options?: {
+        budget?: number;
+        minTrustScore?: number;
+        prefer?: string;
+        limit?: number;
+    }): Promise<Record<string, any>[]>;
+    /** Get trust score for a server. */
+    getTrustScore(serverId: string, window?: string, recompute?: boolean): Promise<TrustScore>;
+    /** Get payment history for an agent. */
+    getPaymentHistory(agentId: string, limit?: number, offset?: number): Promise<PaymentHistoryResponse>;
+    /** Register a new agent identity. */
+    registerAgent(agentId: string, displayName: string, capabilities?: string[]): Promise<Record<string, any>>;
+    /** Send a message between agents. */
+    sendMessage(sender: string, recipient: string, content: string, messageType?: string): Promise<Record<string, any>>;
+    /** Cancel a held escrow and refund the payer. */
+    cancelEscrow(escrowId: string): Promise<EscrowResponse>;
+    /** Refund a settled payment (full or partial). */
+    refundSettlement(settlementId: string, options?: {
+        amount?: number;
+        reason?: string;
+    }): Promise<RefundResponse>;
+    /** Refund a payment intent: voids if pending, reverse-transfers if settled. */
+    refundIntent(intentId: string): Promise<PaymentIntent>;
+    /** Void a pending payment (alias for refundIntent). */
+    voidPayment(intentId: string): Promise<PaymentIntent>;
+    /** Create a recurring payment subscription. */
+    createSubscription(payer: string, payee: string, amount: number, interval: string, options?: {
+        description?: string;
+    }): Promise<SubscriptionResponse>;
+    /** Cancel an active or suspended subscription. */
+    cancelSubscription(subscriptionId: string, options?: {
+        cancelledBy?: string;
+    }): Promise<{
+        id: string;
+        status: string;
+    }>;
+    /** Get subscription details by ID. */
+    getSubscription(subscriptionId: string): Promise<SubscriptionDetailResponse>;
+    /** List subscriptions for an agent. */
+    listSubscriptions(options?: {
+        agentId?: string;
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<SubscriptionListResponse>;
+    /** Register a new service in the marketplace. */
+    registerService(options: {
+        providerId: string;
+        name: string;
+        description: string;
+        category: string;
+        tools?: string[];
+        tags?: string[];
+        endpoint?: string;
+        pricing?: Record<string, any>;
+    }): Promise<ServiceRegistrationResponse>;
+    /** Get a marketplace service by ID. */
+    getService(serviceId: string): Promise<ServiceDetailResponse>;
+    /** Rate a marketplace service (1-5). */
+    rateService(serviceId: string, agentId: string, rating: number, options?: {
+        review?: string;
+    }): Promise<ServiceRatingResponse>;
+    /** Search for servers by name or minimum trust score. */
+    searchServers(options?: {
+        nameContains?: string;
+        minScore?: number;
+        limit?: number;
+    }): Promise<ServerSearchResponse>;
+    /** Get the cryptographic identity for an agent. */
+    getAgentIdentity(agentId: string): Promise<AgentIdentityResponse>;
+    /** Verify that a message was signed by the claimed agent. */
+    verifyAgent(agentId: string, message: string, signature: string): Promise<VerifyAgentResponse>;
+    /** Submit trading bot metrics for platform attestation. */
+    submitMetrics(agentId: string, metrics: Record<string, any>, options?: {
+        dataSource?: string;
+    }): Promise<MetricsSubmissionResponse>;
+    /** Get all verified metric claims for an agent. */
+    getVerifiedClaims(agentId: string): Promise<VerifiedClaimsResponse>;
+    /** Register a webhook endpoint. */
+    registerWebhook(options: {
+        agentId: string;
+        url: string;
+        eventTypes: string[];
+        secret?: string;
+        filterAgentIds?: string[];
+    }): Promise<WebhookResponse>;
+    /** List all registered webhooks for an agent. */
+    listWebhooks(agentId: string): Promise<WebhookListResponse>;
+    /** Delete (deactivate) a webhook by ID. */
+    deleteWebhook(webhookId: string): Promise<WebhookDeleteResponse>;
+    /** Create a new API key for an agent. */
+    createApiKey(agentId: string, options?: {
+        tier?: string;
+    }): Promise<ApiKeyResponse>;
+    /** Rotate an API key: revoke current and create new with same tier. */
+    rotateKey(currentKey: string): Promise<KeyRotationResponse>;
+    /** Publish an event to the cross-product event bus. */
+    publishEvent(eventType: string, source: string, payload?: Record<string, any>): Promise<EventPublishResponse>;
+    /** Query events from the event bus. */
+    getEvents(options?: {
+        eventType?: string;
+        sinceId?: number;
+        limit?: number;
+    }): Promise<EventListResponse>;
+    /** Create a new organization. */
+    createOrg(orgName: string): Promise<OrgResponse>;
+    /** Get organization details and members. */
+    getOrg(orgId: string): Promise<OrgDetailResponse>;
+    /** Add an agent to an organization. */
+    addAgentToOrg(orgId: string, agentId: string): Promise<OrgMemberResponse>;
+    /** Get organization members (convenience alias for getOrg). */
+    getOrgMembers(orgId: string): Promise<OrgDetailResponse>;
+    /** Start a price negotiation with another agent. */
+    negotiatePrice(options: {
+        initiator: string;
+        responder: string;
+        amount: number;
+        serviceId?: string;
+        expiresHours?: number;
+    }): Promise<NegotiationResponse>;
+    /** Get messages for an agent. */
+    getMessages(agentId: string, options?: {
+        threadId?: string;
+        limit?: number;
+    }): Promise<MessageListResponse>;
+}