import type {
  // WorkspaceClient — component execution
  ClientOptions,
  ExecuteOptions,
  PromiseOptions,
  ExecuteComponentResponse,
  ExecutionStreamEvent,
  ExecutionStreamHandlers,
  ExecutionStreamSubscription,
  // WorkflowClient
  TriggerRunResponse,
  WorkflowRunDetail,
  WorkflowRunStatus,
  RunStage,
  StageStatus,
  RunStreamEvent,
  RunStreamStage,
  RunStreamHandlers,
  RunStreamSubscription,
  UpdateComponentRequest,
  UpdateComponentResponse,
} from '@zafeguard/caller-sdk';

interface ClientOptions {
  /** Workspace API key (ws_...) */
  apiKey: string;
  /** Override API base URL. Defaults to https://api.zafeguard.com */
  baseUrl?: string;
}

interface WorkflowClientOptions {
  /** Workspace API key (ws_...) */
  apiKey: string;
  /** UUID of the workflow to trigger. */
  workflowId: string;
  /** Override API base URL. Defaults to https://api.zafeguard.com */
  baseUrl?: string;
}

interface ExecuteOptions {
  /** Execution attempts on failure, 1–3. @default 1 */
  attempts?: number;
  /** Wait up to N ms for inline result. Max 15000. */
  waitForMs?: number;
  /** HTTPS URL to receive completion webhook. */
  callbackUrl?: string;
  /** HMAC-SHA256 key for webhook signature. */
  callbackSecret?: string;
  /** Custom HTTP headers added to the webhook request. */
  callbackHeaders?: Record<string, string>;
}

interface PromiseOptions {
  /** Execution attempts on failure, 1–3. @default 1 */
  attempts?: number;
  /**
   * Max wait time in ms. Rejects with CallerSDKError("Execution timed out")
   * if the execution doesn't complete in time.
   * @default 60_000
   */
  timeoutMs?: number;
}

interface ExecuteComponentResponse {
  id: string;
  module: string;
  status: 'CREATED' | 'RUNNING' | 'COMPLETED' | 'FAILED';
  completed: boolean;
  output: unknown | null;
  error: unknown | null;
  /**
   * Credits billed for this call.
   *
   * `0` indicates this was a free repeat call within the cache window
   * (your workspace's first call within the window for these exact
   * inputs bills normally; subsequent identical calls are free). See
   * "Cache hits and credit usage" in the Execute Component page.
   */
  totalUsage: number;
  callback: {
    url: string | null;
    signed: boolean;
    signatureAlgorithm: 'hmac-sha256-v1' | null;
    headerNames: string[];
    lastAttemptAt: string | null;
    deliveredAt: string | null;
    attemptCount: number;
    lastError: unknown | null;
  };
  createdAt: string;
  updatedAt: string;
}

interface ExecutionStreamEvent {
  id: string;
  status: 'CREATED' | 'RUNNING' | 'COMPLETED' | 'FAILED';
  // `output` and `error` are optional — the server omits them from the wire
  // JSON on non-terminal events.
  output?: unknown | null;  // populated on COMPLETED
  error?: unknown | null;   // populated on FAILED
  timestamp: string;
}

interface ExecutionStreamHandlers {
  /** Called for every status event pushed by the stream. */
  onUpdate(event: ExecutionStreamEvent): void;
  /** Called when the stream closes due to a network error. */
  onError?(err: Error): void;
}

interface ExecutionStreamSubscription {
  /** Unsubscribe and tear down the SSE connection. */
  close(): void;
}

interface ExecutionNamespace {
  /** Fetch current state of an execution by ID. */
  get(executionId: string): Promise<ExecuteComponentResponse>;

  /** Subscribe to live status events for an execution via SSE. */
  stream(
    executionId: string,
    handlers: ExecutionStreamHandlers,
  ): ExecutionStreamSubscription;
}

interface WebhookNamespace {
  /** Re-deliver the completion webhook for an execution. Idempotent. */
  redeliver(executionId: string): Promise<void>;
}

interface TriggerRunResponse {
  /** UUID identifying the new run. */
  runId: string;
  /** Internal job ID for the run. */
  jobId: string;
}

type WorkflowRunStatus =
  | 'CREATED'
  | 'EXECUTING'
  | 'COMPLETED'
  | 'FAILED';

type StageStatus =
  | 'CREATED'
  | 'RUNNING'
  | 'COMPLETED'
  | 'FAILED';

interface RunStage {
  id: string;
  module: string;
  status: StageStatus;
  output: unknown | null;
  error: unknown | null;
  creditUsage: number;
  executionEventId: string | null;
  executionDispatchedAt: string | null;
  /** 1-based retry counter. 1 = first attempt. */
  executionAttempt: number;
  updatedAt: string;
}

interface WorkflowRunDetail {
  id: string;
  status: WorkflowRunStatus;
  pendingStageCount: number;
  failedStageCount: number;
  cancelRequestedAt: string | null;
  cancelReason: string | null;
  totalUsage: number;
  createdAt: string;
  updatedAt: string;
  runStages: RunStage[];
}

interface RunStreamEvent {
  id: string;
  status: WorkflowRunStatus;
  output: {
    totalUsage?: number;
    pendingStageCount?: number;
    failedStageCount?: number;
    cancelRequestedAt?: string | null;
    cancelReason?: string | null;
    nonTerminalStages?: RunStreamStage[];
  };
  timestamp: string;
}

interface RunStreamStage {
  id: string;
  module: string;
  status: 'CREATED' | 'RUNNING';
  referenceId: string;
  /** -1 for non-FOR_EACH stages, otherwise the iteration index. */
  iteration: number;
  parentStageId: string | null;
  executionEventId: string | null;
  executionDispatchedAt: string | null;
  executionAttempt: number;
  updatedAt: string;
}

interface RunStreamHandlers {
  /** Called for every status event emitted by the stream. */
  onUpdate(event: RunStreamEvent): void;
  /** Called when the stream closes due to a connection error. */
  onError?(err: Error): void;
}

interface RunStreamSubscription {
  /** Unsubscribe and release the SSE connection. */
  close(): void;
}

interface UpdateComponentRequest {
  /** New component config (merged with existing values on the server). */
  config?: Record<string, unknown>;
  /** New display name for the component on the canvas. */
  name?: string;
  /** Canvas position [x, y]. */
  position?: [number, number];
}

interface UpdateComponentResponse {
  id: string;
  name: string;
  position: [number, number];
  config: Record<string, unknown>;
  updatedAt: string;
}

{
  "module": "RANDOM_UUID",
  "input": {},
  "config": {},
  "attempts": 1,
  "waitForMs": 5000,
  "callbackUrl": "https://your.app/webhook",
  "callbackSecret": "hmac-secret",
  "callbackHeaders": { "X-Source": "zafeguard" }
}

{
  "id": "3f7a1b2c-...",
  "module": "RANDOM_UUID",
  "status": "CREATED",
  "completed": false,
  "output": null,
  "totalUsage": 0,
  "callback": {
    "url": null, "signed": false, "signatureAlgorithm": null,
    "headerNames": [], "attemptCount": 0,
    "lastAttemptAt": null, "deliveredAt": null, "lastError": null
  },
  "createdAt": "2026-04-20T10:00:00Z",
  "updatedAt": "2026-04-20T10:00:00Z"
}

{
  "id": "3f7a1b2c-...",
  "module": "RANDOM_UUID",
  "status": "COMPLETED",
  "completed": true,
  "output": { "uuid": "a4c2e8f1-..." },
  "totalUsage": 1,
  "callback": {
    "url": null, "signed": false, "signatureAlgorithm": null,
    "headerNames": [], "attemptCount": 0,
    "lastAttemptAt": null, "deliveredAt": null, "lastError": null
  },
  "createdAt": "2026-04-20T10:00:00Z",
  "updatedAt": "2026-04-20T10:00:01Z"
}

interface ExecutionStreamEvent {
  id: string;
  status: 'CREATED' | 'RUNNING' | 'COMPLETED' | 'FAILED';
  output?: unknown;
  error?: unknown;
  timestamp: string;
}

[
  {
    "runId": "9e4c7b1a-...",
    "jobId": "bull-12345"
  }
]

{
  "id": "9e4c7b1a-...",
  "status": "COMPLETED",
  "pendingStageCount": 0,
  "failedStageCount": 0,
  "totalUsage": 14,
  "createdAt": "2026-04-20T10:00:00Z",
  "updatedAt": "2026-04-20T10:00:08Z",
  "runStages": [
    {
      "id": "stage-uuid",
      "module": "GET_EVM_ACCOUNT_BALANCE",
      "status": "COMPLETED",
      "output": { "balance": "1000000" },
      "creditUsage": 3,
      "executionAttempt": 1,
      "updatedAt": "2026-04-20T10:00:05Z"
    }
  ]
}

interface RunStreamEvent {
  id: string;
  status: 'CREATED' | 'EXECUTING' | 'COMPLETED' | 'FAILED';
  output: {
    totalUsage?: number;
    pendingStageCount?: number;
    failedStageCount?: number;
    cancelRequestedAt?: string | null;
    cancelReason?: string | null;
    nonTerminalStages?: Array<{
      id: string;
      module: string;
      status: 'CREATED' | 'RUNNING';
      referenceId: string;
      iteration: number;  // -1 for non-FOR_EACH stages
      parentStageId: string | null;
      executionEventId: string | null;
      executionDispatchedAt: string | null;
      executionAttempt: number;
      updatedAt: string;
    }>;
  };
  timestamp: string;
}

{
  "config": { "url": "https://new-endpoint.com" },
  "name": "Updated Component",
  "position": [120, 340]
}

{
  "message": "Human-readable description",
  "statusCode": 400,
  "error": "Bad Request"
}