@relaycore/sdk 1.0.0

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "moduleResolution": "node",
+        "baseUrl": ".",
+        "paths": {
+            "*": [
+                "*"
+            ]
+        },
+        "composite": true,
+        "declaration": true,
+        "emitDeclarationOnly": false,
+        "outDir": "dist"
+    },
+    "include": [
+        "**/*.ts"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist"
+    ]
+}

package/tsup.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+    entry: ['index.ts'],
+    format: ['cjs', 'esm'],
+    platform: 'node',
+    target: 'node18',
+    dts: true,
+    splitting: false,
+    sourcemap: true,
+    clean: true,
+    // Exclude test files
+    ignoreWatch: ['**/*.test.ts'],
+    skipNodeModulesBundle: true,
+    external: ['fsevents', 'express', 'ethers', '@crypto.com/facilitator-client', 'siwe', '@reown/appkit'],
+    loader: {
+        '.node': 'empty',
+    },
+});

package/types/chat.types.ts

@@ -0,0 +1,146 @@
+/**
+ * Chat Service Types
+ * 
+ * Defines the chat API contract per the In-App Chat Architecture specification.
+ * Chat is a control plane + explainer + orchestrator, NOT an executor.
+ */
+
+export type ChatMode = 'explain' | 'simulate' | 'plan' | 'observe';
+
+export type ChatResponseType = 'explanation' | 'simulation' | 'plan' | 'observation' | 'error';
+
+/**
+ * Chat request structure
+ */
+export interface ChatRequest {
+    /** User's query */
+    query: string;
+    /** Operating mode */
+    mode: ChatMode;
+    /** Context for the request */
+    context?: {
+        sessionId?: string;
+        agentId?: string;
+        taskId?: string;
+        walletAddress?: string;
+    };
+    /** Conversation history */
+    history?: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+}
+
+/**
+ * Proposed action that requires user approval
+ */
+export interface ChatAction {
+    /** Human-readable label */
+    label: string;
+    /** API endpoint to call */
+    endpoint: string;
+    /** HTTP method */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** Request body */
+    body: Record<string, unknown>;
+    /** Whether this action requires explicit user approval */
+    requiresApproval: boolean;
+    /** Estimated cost if applicable */
+    estimatedCost?: {
+        amount: string;
+        currency: string;
+    };
+    /** Risk level */
+    riskLevel?: 'low' | 'medium' | 'high';
+}
+
+/**
+ * Simulation result for dry-run operations
+ */
+export interface SimulationResult {
+    /** What would happen */
+    description: string;
+    /** Expected outcome */
+    expectedOutcome: {
+        success: boolean;
+        estimatedResult?: Record<string, unknown>;
+    };
+    /** Potential risks */
+    risks?: string[];
+    /** Required confirmations */
+    confirmations?: string[];
+    /** Gas/fee estimate */
+    estimatedFees?: {
+        gas?: string;
+        payment?: string;
+        total?: string;
+    };
+}
+
+/**
+ * Chat response structure
+ */
+export interface ChatResponse {
+    /** Response type */
+    type: ChatResponseType;
+    /** Main content (human-readable) */
+    content: string;
+    /** Structured data */
+    data?: Record<string, unknown>;
+    /** Actions user can take (require approval) */
+    actions?: ChatAction[];
+    /** Simulation results (for simulate mode) */
+    simulation?: SimulationResult;
+    /** Data sources used */
+    sources?: Array<{
+        name: string;
+        type: 'indexer' | 'api' | 'contract' | 'database';
+        latencyMs?: number;
+    }>;
+    /** Processing metadata */
+    meta?: {
+        processingTimeMs: number;
+        tokensUsed?: number;
+        mode: ChatMode;
+    };
+}
+
+/**
+ * Chat capabilities per mode
+ */
+export const CHAT_CAPABILITIES = {
+    explain: {
+        description: 'Explain agent decisions, transactions, and system state',
+        canExecute: false,
+        canModify: false,
+    },
+    simulate: {
+        description: 'Dry-run operations before committing',
+        canExecute: false,
+        canModify: false,
+    },
+    plan: {
+        description: 'Create execution plans for user approval',
+        canExecute: false,
+        canModify: false,
+    },
+    observe: {
+        description: 'Summarize trends, anomalies, and system health',
+        canExecute: false,
+        canModify: false,
+    },
+} as const;
+
+/**
+ * Prohibited chat operations
+ * Chat should NEVER do these directly - they require SDK/MCP
+ */
+export const PROHIBITED_OPERATIONS = [
+    'send_transaction',
+    'sign_message',
+    'approve_token',
+    'execute_trade',
+    'release_payment',
+    'create_session',
+    'fund_session',
+] as const;

package/types/x402.types.ts

@@ -0,0 +1,114 @@
+/**
+ * X402 Types - Based on Cronos x402-examples reference implementation
+ * 
+ * These types match the official Cronos x402 protocol specification.
+ */
+
+import type { CronosNetwork, PaymentRequirements, X402OutputSchema } from '@crypto.com/facilitator-client';
+
+/**
+ * Accepted payment scheme for x402 challenges.
+ * Base-compatible format for x402scan and Base-schema consumers.
+ */
+export interface X402Accepts {
+    /** Payment scheme type - always 'exact' for Cronos x402 */
+    scheme: 'exact';
+    /** Target Cronos network for settlement */
+    network: CronosNetwork;
+    /** Maximum amount required in base units (e.g., 1000000 = 1 USDC) */
+    maxAmountRequired: string;
+    /** Canonical resource identifier being protected */
+    resource: string;
+    /** Human-readable description of the protected resource */
+    description: string;
+    /** MIME type of the protected resource response */
+    mimeType: string;
+    /** Destination address that receives the payment */
+    payTo: string;
+    /** Maximum time in seconds to fulfill payment */
+    maxTimeoutSeconds: number;
+    /** Asset contract address for payment */
+    asset: string;
+    /** Optional schema describing successful output */
+    outputSchema?: X402OutputSchema;
+    /** Extra implementation-specific metadata */
+    extra?: {
+        paymentId?: string;
+        [key: string]: unknown;
+    };
+}
+
+/**
+ * Standard x402 402-response body.
+ * Returned when a client must complete an x402 payment challenge.
+ */
+export interface X402Response {
+    /** X402 protocol version */
+    x402Version: number;
+    /** Optional error message */
+    error?: string;
+    /** List of accepted payment options */
+    accepts?: X402Accepts[];
+    /** Optional payer identifier */
+    payer?: string;
+}
+
+/**
+ * Parameters required to settle an x402 payment.
+ */
+export interface X402PayParams {
+    /** Unique identifier for the payment attempt */
+    paymentId: string;
+    /** Encoded payment header from client */
+    paymentHeader: string;
+    /** Payment requirements from prior 402 challenge */
+    paymentRequirements: PaymentRequirements;
+}
+
+/**
+ * Stored record for settled payments.
+ */
+export interface X402PaidRecord {
+    /** Whether settlement succeeded */
+    settled: boolean;
+    /** Settlement transaction hash */
+    txHash?: string;
+    /** Unix timestamp when recorded */
+    at: number;
+    /** Payer address */
+    payer?: string;
+}
+
+/**
+ * Result of a payment settlement attempt.
+ */
+export type X402PayResult =
+    | { ok: true; txHash?: string }
+    | { ok: false; error: 'verify_failed'; details: unknown }
+    | { ok: false; error: 'settle_failed'; details: unknown };
+
+/**
+ * Options for configuring x402 protection middleware.
+ */
+export interface X402ProtectionOptions {
+    /** Cronos network for verification */
+    network: CronosNetwork;
+    /** Destination address for payment */
+    payTo: string;
+    /** Asset contract address */
+    asset: string;
+    /** Maximum amount required in base units */
+    maxAmountRequired: string;
+    /** Maximum timeout in seconds */
+    maxTimeoutSeconds?: number;
+    /** Description of protected resource */
+    description: string;
+    /** MIME type of response */
+    mimeType?: string;
+    /** Resource identifier */
+    resource: string;
+    /** Output schema */
+    outputSchema?: X402OutputSchema;
+    /** Custom entitlement key extractor */
+    getEntitlementKey?: (req: unknown) => string | undefined;
+}