Gateway React API

import {
  SmithersGatewayProvider,
  useGatewayRun,
  useGatewayActions,
} from "smithers-orchestrator/gateway-react";

function App() {
  return (
    <SmithersGatewayProvider options={{ baseUrl: "/" }}>
      <Run runId={RUN_ID} />
    </SmithersGatewayProvider>
  );
}

function Run({ runId }: { runId: string }) {
  const { data, loading, error } = useGatewayRun(runId);
  const { launchRun, submitApproval } = useGatewayActions();
  if (loading) return <p>loading…</p>;
  if (error) return <p>{error.message}</p>;
  return <pre>{String(data?.status ?? "")}</pre>;
}

type GatewayAsyncState<T> = {
  data: T | undefined;
  error: Error | undefined;
  loading: boolean;
  refetch: () => Promise<void>;
};

function SmithersGatewayProvider(props: {
  client?: SmithersGatewayClient;
  options?: SmithersGatewayClientOptions;
  mode?: WorkspaceMode;
  children?: ReactNode;
}): ReactElement;

function createGatewayReactRoot(
  element: ReactElement,
  options?: SmithersGatewayClientOptions & { rootId?: string; mode?: WorkspaceMode },
): SmithersGatewayClient;

createGatewayReactRoot(<App />, { baseUrl: "/", rootId: "root" });

function useSmithersGateway(): SmithersGatewayClient;

function SmithersCollectionsProvider(props: {
  mode?: WorkspaceMode;
  client?: SmithersDataClient;
  queryClient?: QueryClient;
  children?: ReactNode;
}): ReactElement;

function useSmithersCollections(): {
  client: SmithersDataClient;
  collections: SmithersCollections;
  queryClient: QueryClient;
};

function useGatewayConnectionStatus(): {
  status: "idle" | "connecting" | "online" | "offline" | "unauthorized";
  isOnline: boolean;
  reconnectingSince?: number;
};

function useGatewayRun(
  runId: string | undefined,
): GatewayAsyncState<GatewayRunRow>;

function useGatewayRunEvents(
  runId: string | undefined,
  options?: { afterSeq?: number; maxEvents?: number },
): {
  events: GatewayEventFrame[];
  lastHeartbeat: GatewayEventFrame | undefined;
  error: Error | undefined;
  streaming: boolean;
};

function useGatewayRuns(
  params?: ListRunsRequest,
): GatewayAsyncState<GatewayRunSummaryRow[]>;

function useGatewayWorkflows(
  params?: ListWorkflowsRequest,
): GatewayAsyncState<ListWorkflowsResponse>;

function useGatewayApprovals(
  params?: ListApprovalsRequest,
): GatewayAsyncState<ListApprovalsResponse>;

const approvals = useGatewayApprovals({ filter: { runId } });
const { submitApproval } = useGatewayActions();
return (approvals.data ?? []).map((gate) => (
  <button
    key={gate.nodeId}
    onClick={() => submitApproval({ runId, nodeId: gate.nodeId, iteration: gate.iteration, decision: { approved: true } })}
  >
    Approve {gate.requestTitle ?? gate.nodeId}
  </button>
));

function useGatewayCrons(
  params?: CronListRequest,
): GatewayAsyncState<GatewayCronRow[]>;

function useGatewayMemoryFacts(
  namespace?: string,
): GatewayAsyncState<GatewayMemoryFactRow[]>;

function useGatewayNodeOutput(params: {
  runId: string | undefined;
  nodeId: string | undefined;
  iteration?: number;
}): GatewayAsyncState<GatewayRpcPayload<"getNodeOutput">>;

function useGatewayScores(
  runId: string,
  nodeId?: string,
): GatewayAsyncState<GatewayScoreRow[]>;

function useGatewayTickets(
  params?: ListTicketsRequest,
): GatewayAsyncState<GatewayTicketRow[]>;

function useGatewayPrompts(): GatewayAsyncState<GatewayPromptRow[]>;

function useGatewayRpc<Method extends GatewayRpcMethod>(
  method: Method,
  params: GatewayRpcParams<Method>,
  options?: { enabled?: boolean; deps?: readonly unknown[] },
): GatewayAsyncState<GatewayRpcPayload<Method>>;

function useDelegationChain(params: { runId: string | undefined }): {
  graph: DelegationGraph;
  loading: boolean;
  errors: unknown[];
  actions: {
    submitEdit(logicalId: string, editedOutput: unknown, note?: string): Promise<void>;
    skipPreviews(): Promise<void>;
    answerHuman(nodeId: string, iteration: number, value: unknown): Promise<void>;
    submitPoll(answers: DcPollAnswer[], comment?: string): Promise<void>;
  };
};

function useGatewayActions(): {
  launchRun: SmithersGatewayClient["launchRun"];
  resumeRun: SmithersGatewayClient["resumeRun"];
  cancelRun: SmithersGatewayClient["cancelRun"];
  hijackRun: SmithersGatewayClient["hijackRun"];
  rewindRun: SmithersGatewayClient["rewindRun"];
  submitApproval: SmithersGatewayClient["submitApproval"];
  submitSignal: SmithersGatewayClient["submitSignal"];
  cronCreate: SmithersGatewayClient["cronCreate"];
  cronDelete: SmithersGatewayClient["cronDelete"];
  cronRun: SmithersGatewayClient["cronRun"];
};

const { launchRun, submitApproval } = useGatewayActions();
await launchRun({ workflow: "research", input: { topic: "smithers" } });
// `decision` is REQUIRED; that object carries the verdict. Pass `iteration`
// from the approval gate (default 0). Approve:
await submitApproval({ runId: RUN_ID, nodeId: NODE_ID, iteration: 0, decision: { approved: true } });
// Deny:
await submitApproval({ runId: RUN_ID, nodeId: NODE_ID, iteration: 0, decision: { approved: false, note: "not yet" } });

function useGatewayMutation<TVariables = Record<string, unknown>, TData = unknown>(
  method: string,
  options?: { invalidate?: readonly unknown[] },
): {
  mutate: (variables: TVariables) => Promise<TData>;
  mutateSafe: (variables: TVariables) => Promise<TData | undefined>;
  isLoading: boolean;
  error: Error | undefined;
};

import type {
  SmithersCollectionsContextValue,
  GatewayConnectionStatus,
} from "smithers-orchestrator/gateway-react";
// GatewayAsyncState<T> is generic; see its section above for the full shape.