@superblocksteam/library 2.0.89 → 2.0.90

package/dist/lib/index.d.ts

@@ -2,10 +2,11 @@ import { Callback, ControlType, DataType, DataTypeString, EntityDefinition, Head
 import { Dim, EditorConfig, EvaluateOrValueComputedArgs, Property, TailwindPropertyKey } from "@superblocksteam/library-shared";
 import { DataRouter, Location, Params } from "react-router";
 import * as React$2 from "react";
-import React$1, { LegacyRef, ReactNode } from "react";
+import React$1, { LegacyRef, ReactNode, createElement } from "react";
 import { OrchestratorViewMode, PlaceholderInfo, Profile } from "@superblocksteam/shared";
 import { AiContextMode, AppToEditorMessage, Catalog, CatalogWithInternalDetails, ComponentRegistryShareState, ConsoleLogEntry, CreateChild, CreateChild as CreateChild$1, CreateRequest, DeleteMeLibraryApi, DeleteRequest, EditOperationPayload, EditOperationType, EditOperations, EditorConfig as EditorConfig$1, Entity, EntityOutputProp, InitData, InteractionMode, PayloadAction, PropertyInfo, ReparentRequest, RuntimeErrorData, RuntimeSyncComposite, SbApiRunOptions, SbElement, SbSelector, SetPropertiesRequest, SetPropertyRequest, SourceLocation, TransactionInfo, UrlState, ViteMessage, ViteMessageKind, WithBindingIdentifier } from "@superblocksteam/library-shared/types";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { CompiledApi, CompiledStreamingApi } from "@superblocksteam/sdk-api";
 import { Graph } from "@dagrejs/graphlib";
 import { XYCoord } from "react-dnd";
 
@@ -31,18 +32,20 @@ type Group = {
   name: string;
   size: number;
 };
-type Profiles = {
+type DataTags = {
   available: Profile[];
   selected?: Profile;
   default: Profile;
 };
+/** @deprecated Use DataTags instead */
+type Profiles = DataTags;
 declare class SuperblocksAppContext {
   private context?;
   constructor();
   get user(): User | undefined;
   get groups(): Group[] | undefined;
   get selectedProfile(): Profile | undefined;
-  get profiles(): Profiles | undefined;
+  get profiles(): DataTags | undefined;
   setProfile(profileKey: string): void;
   updateContext(context: Partial<SuperblocksAppContext>): void;
   getGlobal(): {
@@ -59,9 +62,14 @@ declare class SuperblocksAppContext {
 }
 declare function useSuperblocksUser(): User | undefined;
 declare function useSuperblocksGroups(): Group[] | undefined;
+declare function useSuperblocksDataTags(): {
+  dataTags: DataTags | undefined;
+  setDataTag: (dataTagKey: string) => void;
+};
+/** @deprecated Use useSuperblocksDataTags instead */
 declare function useSuperblocksProfiles(): {
-  profiles: Profiles | undefined;
-  setProfile: (profileKey: string) => void;
+  profiles: DataTags | undefined;
+  setProfile: (dataTagKey: string) => void;
 };
 declare function getAppMode(): AppMode | undefined;
 //#endregion
@@ -130,6 +138,45 @@ interface StreamEvent {
   };
 }
 type RouteInfo = Omit<UrlState, "host" | "hostname" | "href" | "port" | "protocol">;
+/**
+ * Schema representation for SDK API input/output/chunk schemas.
+ * Contains both TypeScript and JSON Schema formats for display in the UI.
+ */
+interface SdkApiSchemaInfo {
+  /** TypeScript type string representation, e.g., "{ userId: string; limit?: number }" */
+  typescript: string;
+  /** JSON Schema representation for the schema */
+  jsonSchema: object;
+}
+/**
+ * Metadata for an SDK API, sent from the library to ui-code-mode
+ * when an SDK API is registered.
+ */
+interface SdkApiMetadata {
+  /** Unique name of the API */
+  name: string;
+  /** Input schema information */
+  inputSchema: SdkApiSchemaInfo;
+  /** Output schema information (for non-streaming APIs) */
+  outputSchema?: SdkApiSchemaInfo;
+  /** Chunk schema information (for streaming APIs) */
+  chunkSchema?: SdkApiSchemaInfo;
+  /** Whether this is a streaming API */
+  isStreaming: boolean;
+  /** Declared integrations for this API */
+  integrations: Array<{
+    /** Key used in the API code to reference this integration */
+    key: string;
+    /** Plugin ID (e.g., "postgres", "slack") */
+    pluginId: string;
+    /** Integration name (e.g., "Production Postgres") */
+    name: string;
+    /** Integration ID (UUID) */
+    id: string;
+  }>;
+  /** TypeScript source code of the API */
+  sourceCode?: string;
+}
 type RouteChangePayload = Omit<UrlState, "host" | "hostname" | "href" | "pathname" | "port" | "protocol">;
 type AiUpdatesPayload = {
   parentToChild: {
@@ -184,6 +231,11 @@ type AgentInfo = {
 };
 type FromParentToChildMessageTypesMap = {
   "sb-init": InitData;
+  "sdk-execute-api-internal": {
+    apiName: string;
+    input: Record<string, unknown>;
+    callbackId: string;
+  };
   "sb-bootstrap-response": {
     userId?: string;
     appId: string;
@@ -238,7 +290,17 @@ type FromParentToChildMessageTypesMap = {
   "canvas-scale-update": {
     canvasScaleFactor: number;
   };
+  /**
+   * Resolve a promise created by addNewPromise.
+   * Note: callbackId must be at the top level, not nested in payload.
+   * Payload contains the resolution value.
+   */
   "resolve-promise": unknown;
+  /**
+   * Reject a promise created by addNewPromise.
+   * Note: callbackId must be at the top level, not nested in payload.
+   * Payload contains the error object.
+   */
   "reject-promise": unknown;
   "flash-element": {
     elementId: string;
@@ -332,6 +394,35 @@ type FromParentToChildMessageTypesMap = {
     callbackId: string;
     sourceIds: string[];
   };
+  /**
+   * Execute an SDK-based API by name in the iframe.
+   * The parent (ui-code-mode) sends this to the library iframe to execute the API.
+   */
+  "sdk-execute-api": {
+    apiName: string;
+    input: Record<string, unknown>;
+    callbackId: string;
+  };
+  /**
+   * Send a chunk from a streaming query back to the library.
+   * Used during SDK streaming API execution.
+   */
+  "sdk-stream-chunk": {
+    streamId: string;
+    chunk?: unknown;
+    done?: boolean;
+    error?: {
+      code: string;
+      message: string;
+    };
+  };
+  /**
+   * Request the TypeScript source code for an SDK API.
+   */
+  "sdk-get-api-code": {
+    name: string;
+    callbackId: string;
+  };
 };
 type FromParentToChildMessageTypes = keyof FromParentToChildMessageTypesMap;
 type FromChildToParentMessageTypesMap = {
@@ -350,7 +441,17 @@ type FromChildToParentMessageTypesMap = {
     newWindow?: boolean;
   };
   "sb-iframe-track-changes": Record<string, unknown>;
+  /**
+   * Resolve a promise created by addNewPromise.
+   * Note: callbackId must be at the top level, not nested in payload.
+   * Payload contains the resolution value.
+   */
   "resolve-promise": unknown;
+  /**
+   * Reject a promise created by addNewPromise.
+   * Note: callbackId must be at the top level, not nested in payload.
+   * Payload contains the error object.
+   */
   "reject-promise": unknown;
   "sb-editor-request-bootstrap": void;
   "reload-configs": void;
@@ -407,6 +508,63 @@ type FromChildToParentMessageTypesMap = {
     apiId: string;
     callbackId: string;
   };
+  /**
+   * Execute an integration query as part of SDK API execution.
+   * The parent (ui-code-mode) will dispatch executeRequestToIntegration
+   * and resolve the promise with the result.
+   *
+   * For language plugins (Python, JavaScript), the input parameter contains
+   * bindings that should be passed to the API execution request for {{}} resolution.
+   */
+  "sdk-execute-query": {
+    integrationId: string;
+    request: Record<string, unknown>;
+    input?: Record<string, unknown>;
+    callbackId: string;
+  };
+  /**
+   * Execute an SDK-based API by name.
+   * The parent (ui-code-mode) will load the API, validate inputs,
+   * and execute it with the provided input.
+   *
+   * This message is sent from the library iframe to request API execution.
+   */
+  "sdk-execute-api": {
+    apiName: string;
+    input: Record<string, unknown>;
+    callbackId: string;
+  };
+  /**
+   * Resolve integration configs before SDK API execution.
+   * The parent (ui-code-mode) will look up each integration by ID,
+   * ensure it's authenticated, and return the resolved configs.
+   *
+   * This enables upfront auth checks before API execution starts.
+   */
+  "sdk-resolve-integrations": {
+    integrations: Array<{
+      key: string;
+      pluginId: string;
+      id: string;
+    }>;
+    callbackId: string;
+  };
+  /**
+   * Execute a streaming integration query as part of SDK streaming API execution.
+   * The parent (ui-code-mode) will dispatch streaming execution and send
+   * chunks back via sdk-stream-chunk messages.
+   */
+  "sdk-execute-streaming-query": {
+    integrationId: string;
+    request: Record<string, unknown>;
+    streamId: string;
+  };
+  /**
+   * Cancel an in-progress streaming query.
+   */
+  "sdk-cancel-stream": {
+    streamId: string;
+  };
   "set-apis-deployed-mode": {
     apis: Array<DeleteMeLibraryApi & {
       scopeId: string;
@@ -462,6 +620,67 @@ type FromChildToParentMessageTypesMap = {
     eventName: string;
     payload: Record<string, unknown>;
   };
+  /**
+   * Notify the parent when an SDK API is registered (loaded).
+   * Contains metadata including input/output schemas for display in the UI.
+   */
+  "sdk-api-registered": {
+    name: string;
+    metadata: SdkApiMetadata;
+  };
+  /**
+   * Notify the parent when an SDK API is unregistered (HMR unload).
+   */
+  "sdk-api-unregistered": {
+    name: string;
+  };
+  /**
+   * Notify the parent when an SDK API's source code has been updated.
+   * Used for HMR to update the code viewer without full re-registration.
+   */
+  "sdk-api-source-updated": {
+    name: string;
+    sourceCode: string;
+  };
+  /**
+   * Response to sdk-get-api-code request with the TypeScript source code.
+   */
+  "sdk-api-code-response": {
+    callbackId: string;
+    name: string;
+    code?: string;
+    error?: string;
+  };
+  /**
+   * Notify the parent when an SDK API execution starts (from app code).
+   * Used for tracking executions in the SDK API editor's execution log.
+   */
+  "sdk-api-execution-started": {
+    executionId: string;
+    apiName: string;
+    input: Record<string, unknown>;
+  };
+  /**
+   * Notify the parent when an SDK API execution completes successfully.
+   */
+  "sdk-api-execution-completed": {
+    executionId: string;
+    apiName: string;
+    output: unknown;
+    durationMs: number;
+  };
+  /**
+   * Notify the parent when an SDK API execution fails.
+   */
+  "sdk-api-execution-failed": {
+    executionId: string;
+    apiName: string;
+    error: {
+      code: string;
+      message: string;
+    };
+    durationMs: number;
+  };
 } & AppToEditorMessage<PropertiesPanelDefinition$1>;
 type FromChildToParentMessageTypes = keyof FromChildToParentMessageTypesMap;
 //#endregion
@@ -893,6 +1112,22 @@ declare class EditStore {
 }
 //#endregion
 //#region src/lib/internal-details/lib/root-store.d.ts
+/**
+ * User information extracted from JWT for SDK API execution.
+ * Matches the ApiUser interface from @superblocksteam/sdk-api.
+ */
+interface SdkApiUser {
+  /** Unique user identifier from JWT */
+  readonly userId: string;
+  /** User's email address (if available) */
+  readonly email?: string;
+  /** User's display name (if available) */
+  readonly name?: string;
+  /** User's group memberships from JWT */
+  readonly groups: string[];
+  /** Custom claims from JWT */
+  readonly customClaims: Readonly<Record<string, unknown>>;
+}
 declare class RootStore {
   apis: ApiManager;
   componentRegistry: ComponentRegistry;
@@ -902,8 +1137,29 @@ declare class RootStore {
   applicationId: string | undefined;
   userId: string | undefined;
   windowOriginUrl: string | undefined;
+  /**
+   * Current user info for SDK API execution.
+   * Populated from JWT claims when available.
+   */
+  sdkUser: SdkApiUser;
+  /**
+   * Whether the SDK API feature is enabled.
+   * Derived from the application's templateName (see `isSdkApiTemplate()`).
+   * Passed to the library via the `clark.sdk-api.enabled` bootstrap flag.
+   * When false, the YAML-based API system is used instead.
+   */
+  sdkApiEnabled: boolean;
   private editorRegisteredCallbacks;
   constructor();
+  /**
+   * Updates the SDK user info from JWT claims or bootstrap data.
+   */
+  setSdkUser(user: Partial<SdkApiUser>): void;
+  /**
+   * Sets the SDK API feature flag state.
+   * Called during bootstrap with the value from feature flags.
+   */
+  setSdkApiEnabled(enabled: boolean): void;
   setEditStore(editStore: EditStore): void;
   notifyEditorRegistered(): void;
   onEditorRegistered(fn: () => void): void;
@@ -1383,51 +1639,168 @@ type ApiInterfaces<Name extends string> = Name extends keyof SuperblocksAPIRegis
   output: never;
 };
 /**
- * React hook for executing Superblocks APIs with type-safe inputs and outputs.
+ * Get the API path for an API by name.
  *
- * @param name - The name of the registered API to execute
- * @returns An object with `run` and `cancel` functions
+ * When SDK APIs are enabled, paths point to `/server/apis/<name>/api.ts`.
+ * When using legacy YAML mode, paths point to `/apis/<name>/api.yaml`.
+ */
+
+/** Helper type to extract input type from a CompiledApi */
+type ApiInput<T> = T extends CompiledApi<infer TInput, any> ? TInput : never;
+/** Helper type to extract output type from a CompiledApi */
+type ApiOutput<T> = T extends CompiledApi<any, infer TOutput> ? TOutput : never;
+/** Return type for useApi hook */
+interface UseApiResult<TInput, TOutput> {
+  run: (inputs: TInput) => Promise<TOutput | undefined>;
+  cancel: () => Promise<void>;
+}
+/**
+ * API Registry interface for type inference.
+ *
+ * This interface is used with useTypedApi to enable automatic type inference.
+ * Apps define their own ApiRegistry type and pass it to useTypedApi.
  *
  * @example
  * ```typescript
- * const myApi = useApiStateful("getUserData");
+ * // In server/apis/index.ts
+ * const apis = { GetUsers, CreateOrder } as const;
+ * export type ApiRegistry = typeof apis;
  *
- * try {
- *   const result = await myApi.run({ userId: "123" });
- *   console.log(result);
- * } catch (error) {
- *   // error is a string describing what went wrong
- *   console.error(error);
- * }
+ * // In client/hooks/useApi.ts
+ * import type { ApiRegistry } from "../../server/apis/index.js";
+ * import { useTypedApi } from "@superblocksteam/library";
+ * export const useApi = useTypedApi<ApiRegistry>();
  * ```
+ */
+interface ApiRegistry {}
+/**
+ * Conditional return type for useApi.
+ * Returns typed result if the API name is in the registry, otherwise unknown.
+ */
+type UseApiReturnType<TName extends string> = TName extends keyof ApiRegistry ? UseApiResult<ApiInput<ApiRegistry[TName]>, ApiOutput<ApiRegistry[TName]>> : UseApiResult<unknown, unknown>;
+/**
+ * React hook for executing YAML-based Superblocks APIs.
+ *
+ * This is the legacy API system that uses `rootStore.apis.runApiByPath`.
+ * It remains the default when the `sdkApiEnabled` flag is off.
+ *
+ * @param name - The name of the registered API to execute
+ * @returns An object with `run` and `cancel` functions
+ */
+declare function useApiStateful<Name extends RegisteredAPINames, Inputs = ApiInterfaces<Name>["input"], Response = ApiInterfaces<Name>["output"]>(name: Name): {
+  run: (inputs?: Inputs) => Promise<Response | undefined>;
+  cancel: () => Promise<void>;
+};
+/**
+ * React hook for calling APIs with automatic type inference.
  *
- * ## Error Handling
+ * When the SDK API feature flag (`clark.sdk-api.enabled`) is on, this sends
+ * a message to the parent frame which loads and executes the SDK-based API.
  *
- * When an API execution fails, the `run` function throws a **string** error message.
- * The error format can be one of:
+ * When the flag is off, this delegates to the legacy YAML-based API system
+ * which uses `rootStore.apis.runApiByPath`.
  *
- * - **Client errors (4xx)**: System error message from the server
- *   - Example: `"Authentication failed"`, `"Invalid request parameters"`
+ * The flag is set once at bootstrap time and never changes within a session,
+ * so the conditional delegation is safe.
  *
- * - **API execution errors**: Formatted message from unhandled API errors
- *   - Example: `"Error in API: Division by zero"`, `"Error in API: Database connection failed"`
+ * @param apiName - The name of the API to execute (e.g., "GetUsers")
+ * @returns Object with `run` function and `cancel` function
+ */
+declare function useApi<TName extends string>(apiName: TName): UseApiReturnType<TName>;
+declare function useApi<TApi extends CompiledApi<unknown, unknown>>(apiName: string): UseApiResult<ApiInput<TApi>, ApiOutput<TApi>>;
+/**
+ * Type for a registry of compiled APIs.
+ * Used with useTypedApi to enable automatic type inference.
+ */
+type AnyApiRegistry = Record<string, CompiledApi<any, any>>;
+/**
+ * Typed useApi function signature for a specific registry.
+ */
+type TypedUseApi<TRegistry extends AnyApiRegistry> = <TName extends keyof TRegistry & string>(apiName: TName) => UseApiResult<ApiInput<TRegistry[TName]>, ApiOutput<TRegistry[TName]>>;
+/**
+ * Creates a typed version of useApi bound to a specific API registry type.
  *
- * - **Infrastructure errors**: High-level error messages
- *   - Example: `"No application ID was found"`, `"No active agent found"`
+ * This enables full type inference using only type imports from the server,
+ * keeping backend code out of the client bundle.
  *
- * The error is also logged to the console before being thrown.
+ * @returns A typed useApi function
+ */
+declare function useTypedApi<TRegistry extends AnyApiRegistry>(): TypedUseApi<TRegistry>;
+//#endregion
+//#region src/lib/internal-details/use-streaming-api.d.ts
+/**
+ * React hook for calling streaming SDK APIs with real-time chunk delivery.
+ *
+ * Returns an AsyncGenerator that yields chunks as they arrive, allowing
+ * natural iteration with `for await...of`.
+ *
+ * @param api - The imported CompiledStreamingApi definition
+ * @returns Object with `stream` function and `cancel` function
  *
- * ## Usage Notes
+ * @example
+ * ```typescript
+ * import StreamChatApi from "../apis/StreamChat/api";
+ * import { useStreamingApi } from "@superblocksteam/library";
+ *
+ * const { stream, cancel } = useStreamingApi(StreamChatApi);
  *
- * - Always wrap `run()` calls in try/catch blocks to handle errors gracefully
- * - Errors are thrown as strings, not Error objects
- * - If the API executes successfully but returns no data, `run()` returns `undefined`
- * - Use `cancel()` to abort in-flight API requests
+ * // Execute and iterate over chunks
+ * const generator = stream({ prompt: "Hello!" });
+ *
+ * for await (const chunk of generator) {
+ *   console.log(chunk.text);
+ *   // Update UI with each chunk
+ * }
+ * ```
+ *
+ * @example With try/catch for error handling
+ * ```typescript
+ * const { stream } = useStreamingApi(StreamChatApi);
+ *
+ * try {
+ *   for await (const chunk of stream({ prompt: "Hello!" })) {
+ *     appendToOutput(chunk.text);
+ *   }
+ *   console.log("Stream completed!");
+ * } catch (error) {
+ *   console.error("Stream error:", error);
+ * }
+ * ```
  */
-declare function useApiStateful<Name extends RegisteredAPINames, Inputs = ApiInterfaces<Name>["input"], Response = ApiInterfaces<Name>["output"]>(name: Name): {
-  run: (inputs?: Inputs) => Promise<Response | undefined>;
-  cancel: () => Promise<void>;
+declare function useStreamingApi<TInput, TChunk>(api: CompiledStreamingApi<TInput, TChunk>): {
+  stream: (inputs: TInput) => AsyncGenerator<TChunk, void, undefined>;
+  cancel: () => void;
 };
+/**
+ * @deprecated Use the new AsyncGenerator-based API instead.
+ * Callback options for streaming API execution.
+ */
+interface StreamingCallbacks<TChunk> {
+  /** Called for each chunk as it arrives */
+  onChunk?: (chunk: TChunk, index: number) => void;
+  /** Called when streaming completes successfully */
+  onComplete?: (totalChunks: number) => void;
+  /** Called if an error occurs during streaming */
+  onError?: (error: {
+    code: string;
+    message: string;
+  }) => void;
+}
+/**
+ * @deprecated Use the new AsyncGenerator-based API instead.
+ * Result of a streaming API execution.
+ */
+interface StreamingResult {
+  /** Whether the streaming completed successfully */
+  success: boolean;
+  /** Total number of chunks received */
+  totalChunks: number;
+  /** Error details if success is false */
+  error?: {
+    code: string;
+    message: string;
+  };
+}
 //#endregion
 //#region src/lib/user-facing/global-functions.d.ts
 declare function logoutIntegrations(): Promise<void>;
@@ -1609,5 +1982,5 @@ declare function useEmbedEvent(eventName: string, handler: (payload: Record<stri
  */
 declare function useEmitEmbedEvent(): (eventName: string, payload?: Record<string, unknown>) => void;
 //#endregion
-export { type AgentInfo, App, type CreateChild, type CreationContext, type EditorConfig, type EditorTemplate, type FromChildToParentMessageTypes, type FromChildToParentMessageTypesMap, type FromParentToChildMessageTypes, type FromParentToChildMessageTypesMap, PageNotFound, Prop, type PropertiesPanelDefinition, Property, PropsCategory, RouteLoadError, Section, Superblocks, SbProvider as SuperblocksProvider, embedStore, getAppMode, logoutIntegrations, registerComponent, tailwindStylesCategory, useApiStateful as useApi, useEmbedEvent, useEmbedProperties, useEmitEmbedEvent, useSuperblocksGroups, useSuperblocksProfiles, useSuperblocksUser };
+export { type AgentInfo, type AnyApiRegistry, type ApiInput, type ApiOutput, type ApiRegistry, App, type CreateChild, type CreationContext, type EditorConfig, type EditorTemplate, type FromChildToParentMessageTypes, type FromChildToParentMessageTypesMap, type FromParentToChildMessageTypes, type FromParentToChildMessageTypesMap, PageNotFound, Prop, type PropertiesPanelDefinition, Property, PropsCategory, RouteLoadError, Section, type StreamingCallbacks, type StreamingResult, Superblocks, SbProvider as SuperblocksProvider, type TypedUseApi, type UseApiResult, type UseApiReturnType, createElement, embedStore, getAppMode, logoutIntegrations, registerComponent, tailwindStylesCategory, useApi, useApiStateful, useEmbedEvent, useEmbedProperties, useEmitEmbedEvent, useStreamingApi, useSuperblocksDataTags, useSuperblocksGroups, useSuperblocksProfiles, useSuperblocksUser, useTypedApi };
 //# sourceMappingURL=index.d.ts.map