@nordsym/apiclaw 1.3.12 → 1.4.0

package/landing/src/components/ChainTrace.tsx

@@ -0,0 +1,261 @@
+"use client";
+
+import { useMemo } from "react";
+import { CheckCircle2, XCircle, Loader2, PauseCircle, SkipForward, Clock, DollarSign, Sparkles } from "lucide-react";
+
+interface StepExecution {
+  _id: string;
+  stepId: string;
+  stepIndex: number;
+  status: "pending" | "running" | "completed" | "failed" | "skipped";
+  input?: any;
+  output?: any;
+  latencyMs?: number;
+  costCents?: number;
+  error?: {
+    code: string;
+    message: string;
+    retryCount?: number;
+  };
+  parallelGroup?: string;
+  createdAt: number;
+  startedAt?: number;
+  completedAt?: number;
+}
+
+interface ChainTraceProps {
+  chain: {
+    _id: string;
+    status: string;
+    totalCostCents: number;
+    totalLatencyMs: number;
+    startedAt?: number;
+    completedAt?: number;
+    steps?: any[];
+  };
+  executions: StepExecution[];
+  tokensSaved: number;
+}
+
+export function ChainTrace({ chain, executions, tokensSaved }: ChainTraceProps) {
+  // Calculate timeline boundaries
+  const timelineBounds = useMemo(() => {
+    if (executions.length === 0) return { start: 0, end: 1000, duration: 1000 };
+
+    const startTimes = executions
+      .filter((e) => e.startedAt)
+      .map((e) => e.startedAt!);
+    const endTimes = executions
+      .filter((e) => e.completedAt)
+      .map((e) => e.completedAt!);
+
+    const start = startTimes.length > 0 ? Math.min(...startTimes) : chain.startedAt || Date.now();
+    const end = endTimes.length > 0 ? Math.max(...endTimes) : chain.completedAt || Date.now();
+    const duration = Math.max(end - start, 1);
+
+    return { start, end, duration };
+  }, [executions, chain]);
+
+  // Group parallel executions
+  const groupedExecutions = useMemo(() => {
+    const groups: { group: string | null; steps: StepExecution[] }[] = [];
+    let currentGroup: string | null = null;
+    let currentSteps: StepExecution[] = [];
+
+    executions.forEach((exec) => {
+      if (exec.parallelGroup !== currentGroup) {
+        if (currentSteps.length > 0) {
+          groups.push({ group: currentGroup, steps: currentSteps });
+        }
+        currentGroup = exec.parallelGroup || null;
+        currentSteps = [exec];
+      } else {
+        currentSteps.push(exec);
+      }
+    });
+
+    if (currentSteps.length > 0) {
+      groups.push({ group: currentGroup, steps: currentSteps });
+    }
+
+    return groups;
+  }, [executions]);
+
+  const getStatusIcon = (status: string) => {
+    switch (status) {
+      case "completed":
+        return <CheckCircle2 className="w-3.5 h-3.5 text-green-500" />;
+      case "running":
+        return <Loader2 className="w-3.5 h-3.5 text-blue-500 animate-spin" />;
+      case "failed":
+        return <XCircle className="w-3.5 h-3.5 text-red-500" />;
+      case "skipped":
+        return <SkipForward className="w-3.5 h-3.5 text-gray-500" />;
+      case "paused":
+        return <PauseCircle className="w-3.5 h-3.5 text-yellow-500" />;
+      default:
+        return <Clock className="w-3.5 h-3.5 text-gray-500" />;
+    }
+  };
+
+  const getBarColor = (status: string) => {
+    switch (status) {
+      case "completed":
+        return "bg-green-500";
+      case "running":
+        return "bg-blue-500 animate-pulse";
+      case "failed":
+        return "bg-red-500";
+      case "skipped":
+        return "bg-gray-500";
+      case "paused":
+        return "bg-yellow-500";
+      default:
+        return "bg-gray-600";
+    }
+  };
+
+  const formatDuration = (ms: number) => {
+    if (ms < 1000) return `${ms}ms`;
+    return `${(ms / 1000).toFixed(1)}s`;
+  };
+
+  const formatCost = (cents: number) => {
+    if (cents === 0) return "$0.00";
+    return `$${(cents / 100).toFixed(2)}`;
+  };
+
+  const calculateBarPosition = (step: StepExecution) => {
+    const start = step.startedAt || timelineBounds.start;
+    const end = step.completedAt || (step.startedAt ? step.startedAt + (step.latencyMs || 0) : timelineBounds.end);
+
+    const left = ((start - timelineBounds.start) / timelineBounds.duration) * 100;
+    const width = ((end - start) / timelineBounds.duration) * 100;
+
+    return {
+      left: `${Math.max(0, left)}%`,
+      width: `${Math.max(2, Math.min(100 - left, width))}%`,
+    };
+  };
+
+  // Get provider info from step definition
+  const getStepProvider = (stepId: string) => {
+    const stepDef = chain.steps?.find((s: any) => s.id === stepId);
+    return stepDef?.provider || "unknown";
+  };
+
+  return (
+    <div className="bg-black/30 rounded-xl border border-white/10 overflow-hidden">
+      {/* Header */}
+      <div className="px-4 py-3 border-b border-white/10 flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          <span className="text-sm font-medium">Chain:</span>
+          <code className="text-xs text-white/60 font-mono">{chain._id.slice(0, 16)}...</code>
+        </div>
+        <div className="flex items-center gap-4 text-sm text-white/60">
+          <span className="flex items-center gap-1">
+            <Clock className="w-3.5 h-3.5" />
+            Total: {formatDuration(chain.totalLatencyMs)}
+          </span>
+        </div>
+      </div>
+
+      {/* Timeline */}
+      <div className="p-4 space-y-2">
+        {groupedExecutions.map(({ group, steps }, groupIndex) => (
+          <div key={group || groupIndex}>
+            {/* Parallel group indicator */}
+            {group && steps.length > 1 && (
+              <div className="text-xs text-white/40 mb-1 flex items-center gap-1">
+                <span className="px-1.5 py-0.5 bg-white/10 rounded">Parallel</span>
+              </div>
+            )}
+            
+            {/* Steps in group */}
+            <div className={group && steps.length > 1 ? "pl-4 border-l-2 border-white/10 space-y-2" : "space-y-2"}>
+              {steps.map((step) => {
+                const position = calculateBarPosition(step);
+                return (
+                  <div key={step._id} className="flex items-center gap-3">
+                    {/* Step name */}
+                    <div className="w-24 flex-shrink-0 flex items-center gap-2">
+                      {getStatusIcon(step.status)}
+                      <span className="text-sm font-mono truncate" title={step.stepId}>
+                        {step.stepId}
+                      </span>
+                    </div>
+
+                    {/* Gantt bar */}
+                    <div className="flex-1 h-6 bg-white/5 rounded relative overflow-hidden">
+                      <div
+                        className={`absolute top-0 h-full rounded ${getBarColor(step.status)}`}
+                        style={{
+                          left: position.left,
+                          width: position.width,
+                        }}
+                      />
+                      {/* Time markers - simplified */}
+                      <div className="absolute inset-0 flex items-center px-2">
+                        <span
+                          className="text-xs font-mono text-white/80 drop-shadow-sm"
+                          style={{
+                            marginLeft: position.left,
+                          }}
+                        >
+                          {formatDuration(step.latencyMs || 0)}
+                        </span>
+                      </div>
+                    </div>
+
+                    {/* Cost */}
+                    <div className="w-16 text-right text-xs text-white/60">
+                      {formatCost(step.costCents || 0)}
+                    </div>
+                  </div>
+                );
+              })}
+            </div>
+          </div>
+        ))}
+      </div>
+
+      {/* Footer */}
+      <div className="px-4 py-3 border-t border-white/10 flex items-center justify-between text-sm">
+        <div className="flex items-center gap-4">
+          <span className="flex items-center gap-1 text-white/60">
+            <DollarSign className="w-3.5 h-3.5" />
+            Total Cost: <span className="text-white font-medium">{formatCost(chain.totalCostCents)}</span>
+          </span>
+        </div>
+        <div className="flex items-center gap-1 text-white/60">
+          <Sparkles className="w-3.5 h-3.5 text-yellow-500" />
+          <span>Tokens Saved: <span className="text-yellow-500 font-medium">~{tokensSaved.toLocaleString()}</span></span>
+        </div>
+      </div>
+
+      {/* Legend */}
+      <div className="px-4 py-2 border-t border-white/5 flex items-center gap-4 text-xs text-white/40">
+        <div className="flex items-center gap-1">
+          <div className="w-3 h-3 rounded bg-green-500" />
+          <span>Completed</span>
+        </div>
+        <div className="flex items-center gap-1">
+          <div className="w-3 h-3 rounded bg-blue-500" />
+          <span>Running</span>
+        </div>
+        <div className="flex items-center gap-1">
+          <div className="w-3 h-3 rounded bg-red-500" />
+          <span>Failed</span>
+        </div>
+        <div className="flex items-center gap-1">
+          <div className="w-3 h-3 rounded bg-yellow-500" />
+          <span>Paused</span>
+        </div>
+        <div className="flex items-center gap-1">
+          <div className="w-3 h-3 rounded bg-gray-500" />
+          <span>Skipped</span>
+        </div>
+      </div>
+    </div>
+  );
+}

package/landing/src/lib/stats.json

@@ -4,7 +4,7 @@
   "directCallCount": 18,
   "categoryCount": 13,
   "lastUpdated": "2026-02-27T09:10:41.344767",
-  "generatedAt": "2026-03-01T21:34:51.471Z",
+  "generatedAt": "2026-03-02T00:02:51.920Z",
   "categoryBreakdown": {
     "Finance": 1179,
     "Auth & Security": 491,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nordsym/apiclaw",
-  "version": "1.3.12",
+  "version": "1.4.0",
   "description": "The API layer for AI agents. 22,000+ APIs. Direct Call. Works with any MCP-compatible agent.",
   "type": "module",
   "main": "dist/index.js",

package/src/chain-types.ts

@@ -0,0 +1,270 @@
+/**
+ * Chain Execution Types for APIClaw
+ * 
+ * Enables multi-step API orchestration with:
+ * - Sequential execution
+ * - Parallel execution
+ * - Conditional branching
+ * - Loops (forEach, map-reduce)
+ * - Error handling & retry
+ * - Cross-step references ($stepId.property)
+ */
+
+// ============================================
+// CHAIN STEP TYPES
+// ============================================
+
+/**
+ * Base step configuration
+ */
+export interface ChainStepBase {
+  id: string;
+  provider: string;
+  action: string;
+  params?: Record<string, any>;
+  onError?: ErrorHandler;
+}
+
+/**
+ * Parallel execution step - runs multiple steps concurrently
+ */
+export interface ParallelStep {
+  parallel: ChainStepBase[];
+}
+
+/**
+ * Conditional step - executes based on condition
+ */
+export interface ConditionalStep {
+  if: string;  // Expression like "$step1.success === true"
+  then: ChainStepBase | ChainStep;
+  else?: ChainStepBase | ChainStep;
+}
+
+/**
+ * Loop step - iterates over array
+ */
+export interface ForEachStep {
+  forEach: string;  // Reference like "$step1.results"
+  as: string;       // Variable name for current item
+  do: ChainStepBase;
+}
+
+/**
+ * Map step - transforms array
+ */
+export interface MapStep {
+  map: {
+    input: string;
+    fn: ChainStepBase;
+  };
+}
+
+/**
+ * Reduce step - aggregates results
+ */
+export interface ReduceStep {
+  reduce: {
+    input: string;
+    fn: ChainStepBase;
+  };
+}
+
+/**
+ * Union type for all step variants
+ */
+export type ChainStep = 
+  | ChainStepBase 
+  | ParallelStep 
+  | ConditionalStep 
+  | ForEachStep
+  | MapStep
+  | ReduceStep;
+
+// ============================================
+// ERROR HANDLING
+// ============================================
+
+export interface RetryConfig {
+  attempts?: number;
+  maxAttempts?: number;
+  backoff?: number[] | 'exponential' | 'linear';
+  backoffMs?: number;
+}
+
+export interface ErrorHandler {
+  retry?: RetryConfig;
+  fallback?: ChainStepBase;
+  abort?: boolean;
+}
+
+export type ErrorPolicy = 'fail-fast' | 'best-effort' | 'transactional';
+
+export interface RollbackAction {
+  if: string;
+  do: ChainStepBase;
+}
+
+export interface ChainErrorPolicy {
+  mode: ErrorPolicy;
+  rollback?: RollbackAction[];
+}
+
+// ============================================
+// CHAIN CONFIGURATION
+// ============================================
+
+export interface ChainLimits {
+  maxSteps?: number;
+  maxParallel?: number;
+  maxCost?: { cents: number };
+}
+
+export interface ChainOptions {
+  continueOnError?: boolean;
+  timeout?: number;        // Max execution time in ms
+  async?: boolean;         // Return immediately with chainId
+  webhook?: string;        // URL to call on completion
+  errorPolicy?: ChainErrorPolicy;
+  limits?: ChainLimits;
+}
+
+// ============================================
+// CHAIN EXECUTION REQUEST
+// ============================================
+
+export interface ChainRequest extends ChainOptions {
+  chain: ChainStep[];
+}
+
+// ============================================
+// STEP RESULT
+// ============================================
+
+export type StepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+
+export interface StepResult {
+  id: string;
+  status: StepStatus;
+  result?: any;
+  error?: string;
+  errorCode?: string;
+  latencyMs: number;
+  cost?: { cents: number };
+  retryAttempts?: number;
+}
+
+// ============================================
+// CHAIN RESPONSE
+// ============================================
+
+export interface ChainSuccessResponse {
+  success: true;
+  chainId: string;
+  steps: StepResult[];
+  finalResult: any;
+  totalLatencyMs: number;
+  totalCost: { cents: number };
+  tokensSaved: number;
+}
+
+export interface ChainErrorResponse {
+  success: false;
+  chainId: string;
+  completedSteps: string[];
+  failedStep: {
+    id: string;
+    error: string;
+    code?: string;
+    retryAfter?: number;
+  };
+  partialResults: Record<string, any>;
+  canResume: boolean;
+  resumeToken?: string;
+}
+
+export type ChainResponse = ChainSuccessResponse | ChainErrorResponse;
+
+// ============================================
+// ASYNC CHAIN STATUS
+// ============================================
+
+export interface AsyncChainResponse {
+  chainId: string;
+  status: 'running' | 'completed' | 'failed';
+  estimatedCompletion?: string;
+  statusUrl: string;
+}
+
+export interface ChainStatusResponse {
+  chainId: string;
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  progress: {
+    completedSteps: number;
+    totalSteps: number;
+    currentStep?: string;
+  };
+  startedAt: string;
+  completedAt?: string;
+  result?: ChainResponse;
+}
+
+// ============================================
+// RESUME CHAIN
+// ============================================
+
+export interface ResumeChainRequest {
+  resumeToken: string;
+  overrides?: Record<string, Record<string, any>>;  // stepId -> params overrides
+}
+
+// ============================================
+// STORED CHAIN TEMPLATES
+// ============================================
+
+export interface ChainInput {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  required?: boolean;
+  default?: any;
+  description?: string;
+}
+
+export interface ChainTemplate {
+  name: string;
+  description?: string;
+  inputs: Record<string, ChainInput>;
+  chain: ChainStep[];
+}
+
+export interface UseChainRequest {
+  useChain: string;
+  inputs: Record<string, any>;
+}
+
+// ============================================
+// TYPE GUARDS
+// ============================================
+
+export function isParallelStep(step: ChainStep): step is ParallelStep {
+  return 'parallel' in step;
+}
+
+export function isConditionalStep(step: ChainStep): step is ConditionalStep {
+  return 'if' in step && 'then' in step;
+}
+
+export function isForEachStep(step: ChainStep): step is ForEachStep {
+  return 'forEach' in step && 'do' in step;
+}
+
+export function isMapStep(step: ChainStep): step is MapStep {
+  return 'map' in step;
+}
+
+export function isReduceStep(step: ChainStep): step is ReduceStep {
+  return 'reduce' in step;
+}
+
+export function isBaseStep(step: ChainStep): step is ChainStepBase {
+  return 'provider' in step && 'action' in step;
+}