@tangle-network/sandbox-ui 0.116.7 → 0.116.9

package/dist/integrations.d.ts

@@ -1,15 +1,11 @@
 import * as React$1 from "react";
+import { ReactNode } from "react";
 //#region src/integrations/types.d.ts
-/**
- * Shapes for the integrations primitives. Mirrors the platform's
- * `/v1/integrations/*` response shape so consumers can pipe payloads
- * straight through. Defined here (rather than imported from
- * `@tangle-network/agent-runtime/platform`) so the UI package stays
- * leaf-level — no dependency on the server-side client.
- */
+/** Legacy endpoint shapes, retained for useIntegrations and IntegrationsPanel. */
 interface IntegrationConnection {
   id: string;
   providerId: string;
+  /** Absent on provider-keyed hubs. */
   connectorId?: string;
   status: "connected" | "pending" | "revoked" | "expired" | (string & {});
   grantedScopes?: string[];
@@ -27,15 +23,10 @@ interface IntegrationConnector {
 interface IntegrationProvider {
   providerId: string;
   displayName?: string;
-  /** The hub catalog's name for the provider ("GitHub", "Google Sheets"). */
   title?: string;
   description?: string;
   iconUrl?: string;
   connectors?: IntegrationConnector[];
-  /**
-   * True when the platform can currently receive this provider's events.
-   * Absent means the platform predates inbound-readiness discovery.
-   */
   eventIngressConfigured?: boolean;
 }
 interface IntegrationHealth {
@@ -44,8 +35,6 @@ interface IntegrationHealth {
   checkedAt?: string;
   message?: string;
 }
-//#endregion
-//#region src/integrations/integrations-panel.d.ts
 type IntegrationSort = "featured" | "alpha";
 interface IntegrationConnectionAction {
   id: string;
@@ -59,63 +48,214 @@ interface IntegrationsPanelProps {
   healthByConnectionId?: Record<string, IntegrationHealth>;
   isLoading?: boolean;
   error?: Error | null;
-  /**
-   * Invoked when the user clicks an unconnected provider tile. The consumer
-   * should call its data hook's `connect(...)` action.
-   */
   onConnect: (input: {
     providerId: string;
     connectorId: string;
   }) => void | Promise<void>;
-  /**
-   * Invoked when the user confirms disconnecting a live connection from the
-   * disconnect control on a connected tile. May return a promise; the
-   * confirmation dialog shows a loading state until it settles and surfaces a
-   * thrown error inline.
-   */
+  /** Confirmation remains open on rejection; cancellation remains available in flight. */
   onDisconnect: (connectionId: string) => void | Promise<void>;
-  /**
-   * Resolver for a connected app's management page URL. When it returns a URL,
-   * the connected tile's body and the overflow menu's "Manage" item become a
-   * real link opened in a new tab (so cmd/middle-click and "open in new tab"
-   * work). Return undefined to omit Manage for a given connection. Preferred
-   * over `onManage` — only fall back to the callback when the URL must be minted
-   * imperatively on click (e.g. a one-time token).
-   */
+  /** Preferred over onManage. Legacy links retain their new-window behavior. */
   getManageHref?: (connection: IntegrationConnection) => string | undefined;
-  /**
-   * Imperative fallback for opening a connected app's management page, used only
-   * when `getManageHref` is not supplied (or returns undefined). The consumer is
-   * responsible for opening the page (e.g. `window.open(...)`).
-   */
   onManage?: (input: {
     connectionId: string;
     providerId: string;
   }) => void | Promise<void>;
-  /** Consumer-owned access context shown below the connected account. */
   getConnectionContext?: (connection: IntegrationConnection) => string | undefined;
-  /** Additional authorized actions in the connected card menu. */
   getConnectionActions?: (connection: IntegrationConnection) => IntegrationConnectionAction[];
-  /** Empty-state message when the catalog hasn't loaded any providers. */
   emptyCatalogLabel?: string;
-  /**
-   * Provider ids surfaced first (in this order) before the rest are sorted
-   * alphabetically. Matching is normalized (case / separators ignored).
-   * Defaults to a curated list of common GTM/work providers.
-   */
+  /** Normalized provider IDs, in order, before the alphabetic tail. */
   featuredIds?: string[];
-  /** Initial sort mode. Defaults to "featured". */
   defaultSort?: IntegrationSort;
-  /**
-   * Tiles the loading skeleton draws. A skeleton exists to reserve the space
-   * the real content will take, so pass the catalog size you expect when the
-   * consumer knows it; the default fills two rows at the widest breakpoint.
-   */
   skeletonCount?: number;
   className?: string;
 }
+/** Display-only contracts. No Hub SDK, credentials, grants, or policy inference. */
+type IntegrationTone = "neutral" | "success" | "warning" | "error";
+interface IntegrationCapabilities {
+  manage?: boolean;
+  disconnect?: boolean;
+  test?: boolean;
+  editPermissions?: boolean;
+  resetPermissions?: boolean;
+}
+interface IntegrationDisplayAction {
+  id: string;
+  label: string;
+  disabled?: boolean;
+  /** The owner handles asynchronous outcomes and supplies updated display state. */
+  onSelect: () => void;
+}
+interface IntegrationDisplayConnection {
+  id: string;
+  accountDisplay?: string | null;
+  statusLabel: string;
+  statusTone?: IntegrationTone;
+  /** Already formatted by the owner (last used, access context, etc.). */
+  detail?: string;
+  capabilities: IntegrationCapabilities;
+  /** Consumer-owned destination; the library never builds a Platform URL. */
+  manageHref?: string;
+  /** Only needed by the legacy panel's existing link contract. */
+  manageInNewWindow?: boolean;
+  actions?: readonly IntegrationDisplayAction[];
+}
+interface IntegrationDisplayProvider {
+  providerId: string;
+  title: string;
+  description?: string;
+  iconUrl?: string;
+  category?: string | null;
+  /** Optional local provider-information destination. */
+  to?: string;
+}
+interface IntegrationsProviderRow extends IntegrationDisplayProvider {
+  kind: "provider";
+  connections: readonly IntegrationDisplayConnection[];
+  /** Explicit selection. null never selects an arbitrary account. */
+  selectedConnectionId: string | null;
+  canConnect: boolean;
+  /** A display hint for the owner's connect callback, not an auth implementation. */
+  authKind?: string | null;
+}
+interface IntegrationsAppRow extends IntegrationDisplayProvider {
+  kind: "app";
+  logoProviderId: string;
+  installedCount: number;
+  to: string;
+}
+type IntegrationsCatalogRow = IntegrationsProviderRow | IntegrationsAppRow;
+interface IntegrationsCatalogProps {
+  /** Order belongs to the owner; filtering does not reorder active accounts. */
+  rows: readonly IntegrationsCatalogRow[];
+  query: string;
+  onQueryChange: (query: string) => void;
+  categoryFilter?: string;
+  onCategoryFilterChange?: (category: string) => void;
+  sort?: IntegrationSort;
+  onSortChange?: (sort: IntegrationSort) => void;
+  onSelectConnection: (providerId: string, connectionId: string | null) => void;
+  onConnect?: (row: IntegrationsProviderRow) => void;
+  onManage?: (connection: IntegrationDisplayConnection, row: IntegrationsProviderRow) => void;
+  onDisconnect?: (connection: IntegrationDisplayConnection, row: IntegrationsProviderRow) => void;
+  onRequestIntegration?: (prefill: string) => void;
+  onRetry?: () => void;
+  loading?: boolean;
+  error?: string | null;
+  actionError?: string | null;
+  connectError?: string | null;
+  busyProviderId?: string | null;
+  /** Compact facade reserves its context line before any account has loaded. */
+  reserveConnectionContext?: boolean;
+  skeletonCount?: number;
+  emptyCatalogLabel?: string;
+  title?: string;
+  description?: string;
+  /** One renderer; tiles preserves the public panel's compact geometry. */
+  layout?: "cards" | "tiles";
+  className?: string;
+}
+interface IntegrationPermissionOption {
+  value: string;
+  label: string;
+}
+interface IntegrationPermissionDisplay {
+  actionPath: string;
+  title: string;
+  riskLabel: string;
+  riskTone?: IntegrationTone;
+  /** Supplied effective decision; null remains unknown, never Allow/Ask. */
+  decision: string | null;
+  decisionOptions: readonly IntegrationPermissionOption[];
+  sourceLabel: string;
+  canReset?: boolean;
+  disabled?: boolean;
+}
+interface IntegrationPermissionGroup {
+  id: string;
+  title: string;
+  description?: string;
+  collapsed?: boolean;
+  rows: readonly IntegrationPermissionDisplay[];
+}
+interface IntegrationConnectionDetails {
+  loading?: boolean;
+  busy?: boolean;
+  error?: string | null;
+  testResult?: {
+    message: string;
+    tone: IntegrationTone;
+  };
+  permissionGroups?: readonly IntegrationPermissionGroup[];
+}
+interface IntegrationConnectionDetailProps {
+  provider: IntegrationDisplayProvider;
+  connections: readonly IntegrationDisplayConnection[];
+  selectedConnectionId: string | null;
+  onSelectConnection: (connectionId: string | null) => void;
+  /** Keying all outcomes by ID prevents another account's policy flashing on selection. */
+  detailsByConnectionId: Readonly<Record<string, IntegrationConnectionDetails | undefined>>;
+  loading?: boolean;
+  error?: string | null;
+  backHref?: string;
+  description?: string;
+  onRetry?: (connectionId: string | null) => void;
+  onTestConnection?: (connectionId: string) => void;
+  onDisconnect?: (connectionId: string) => void;
+  onDecisionChange?: (connectionId: string, actionPath: string, decision: string) => void;
+  onResetDecision?: (connectionId: string, actionPath: string) => void;
+  className?: string;
+}
+interface IntegrationParameterField {
+  key: string;
+  label: string;
+  description?: string;
+  placeholder?: string;
+  required?: boolean;
+}
+interface IntegrationConnectDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  providerId: string;
+  title: string;
+  description?: string | null;
+  busy?: boolean;
+  error?: string | null;
+  /** Caller owns validation, requests, failures and closing on success. */
+  onSubmit: () => void;
+  canSubmit?: boolean;
+  /** Provider-specific fields/validation remain in the application. */
+  children?: ReactNode;
+}
+interface ApiKeyConnectDialogProps extends IntegrationConnectDialogProps {
+  /** Transient controlled input only; never retained by this package. */
+  value: string;
+  onValueChange: (value: string) => void;
+}
+interface OAuthConnectionParameterDialogProps extends IntegrationConnectDialogProps {
+  parameters: readonly IntegrationParameterField[];
+  values: Readonly<Record<string, string>>;
+  onValueChange: (key: string, value: string) => void;
+}
+//#endregion
+//#region src/integrations/integrations-panel.d.ts
+/** Compatibility facade: legacy effects/sorting, one controlled catalog renderer. */
 export declare function IntegrationsPanel({ catalog, connections, healthByConnectionId, isLoading, error, onConnect, onDisconnect, getManageHref, onManage, getConnectionContext, getConnectionActions, emptyCatalogLabel, featuredIds, defaultSort, skeletonCount, className }: IntegrationsPanelProps): React$1.JSX.Element;
 //#endregion
+//#region src/integrations/integrations-catalog.d.ts
+export declare function catalogRowActive(row: IntegrationsCatalogRow): boolean;
+/** Platform's catalog presentation, with app-owned state, destinations and effects. */
+export declare function IntegrationsCatalog({ rows, query, onQueryChange, categoryFilter, onCategoryFilterChange, sort, onSortChange, onSelectConnection, onConnect, onManage, onDisconnect, onRequestIntegration, onRetry, loading, error, actionError, connectError, busyProviderId, reserveConnectionContext, skeletonCount, emptyCatalogLabel, title, description, layout, className }: IntegrationsCatalogProps): import("react").JSX.Element;
+//#endregion
+//#region src/integrations/connection-detail.d.ts
+/** Platform's permission layout, without its fetching, defaults or persistence. */
+export declare function IntegrationConnectionDetail({ provider, connections, selectedConnectionId, onSelectConnection, detailsByConnectionId, loading, error, backHref, description, onRetry, onTestConnection, onDisconnect, onDecisionChange, onResetDecision, className }: IntegrationConnectionDetailProps): import("react").JSX.Element;
+//#endregion
+//#region src/integrations/connection-dialogs.d.ts
+/** Key bytes remain in owner-controlled value/onValueChange; no request or storage. */
+export declare function ApiKeyConnectDialog(props: ApiKeyConnectDialogProps): React$1.JSX.Element;
+/** Parameter schema/values and all auth behavior belong to the owner. */
+export declare function OAuthConnectionParameterDialog(props: OAuthConnectionParameterDialogProps): React$1.JSX.Element;
+//#endregion
 //#region src/integrations/use-integrations.d.ts
 /**
  * Endpoint contract expected on the consumer app's server (which
@@ -140,6 +280,8 @@ interface UseIntegrationsOptions {
   fetchImpl?: typeof fetch;
   /** Whether the initial load happens automatically on mount. */
   autoLoad?: boolean;
+  /** Refresh on visible focus/visibility return and persisted pageshow. Default: false. */
+  refreshOnReturn?: boolean;
 }
 interface UseIntegrationsResult {
   catalog: IntegrationProvider[];
@@ -147,10 +289,11 @@ interface UseIntegrationsResult {
   healthByConnectionId: Record<string, IntegrationHealth>;
   isLoading: boolean;
   error: Error | null;
+  /** Coalesces requests with at most one trailing refresh; resolves after the queue drains. */
   refresh: () => Promise<void>;
-  /** Kick off OAuth — navigates the window on success. */
+  /** Kick off OAuth — navigates on success; rejects with AbortError when its lifetime ends. */
   connect: (input: ConnectInput) => Promise<void>;
-  /** Revoke a connection by id; refreshes the connections list. */
+  /** Revoke by id and refresh; rejects with AbortError when its lifetime ends. */
   disconnect: (connectionId: string) => Promise<void>;
 }
 interface ConnectInput {
@@ -163,7 +306,7 @@ interface ConnectInput {
   returnUrl: string;
   requestedScopes?: string[];
 }
-export declare function useIntegrations({ apiBaseUrl, fetchImpl, autoLoad }: UseIntegrationsOptions): UseIntegrationsResult;
+export declare function useIntegrations({ apiBaseUrl, fetchImpl, autoLoad, refreshOnReturn }: UseIntegrationsOptions): UseIntegrationsResult;
 //#endregion
 //#region src/integrations/provider-logo.d.ts
 /**
@@ -198,4 +341,4 @@ interface ProviderIconProps {
  */
 export declare function ProviderIcon({ id, iconUrl, displayName, size, className }: ProviderIconProps): React$1.JSX.Element;
 //#endregion
-export type { ConnectInput, IntegrationConnection, IntegrationConnectionAction, IntegrationConnector, IntegrationHealth, IntegrationProvider, IntegrationSort, IntegrationsPanelProps, ProviderIconProps, UseIntegrationsOptions, UseIntegrationsResult };
+export { ApiKeyConnectDialog as ApiKeyConnectModal, type ApiKeyConnectDialogProps, type ConnectInput, type IntegrationCapabilities, type IntegrationConnectDialogProps, type IntegrationConnection, type IntegrationConnectionAction, type IntegrationConnectionDetailProps, type IntegrationConnectionDetails, type IntegrationConnector, type IntegrationDisplayAction, type IntegrationDisplayConnection, type IntegrationDisplayProvider, type IntegrationHealth, type IntegrationParameterField, type IntegrationPermissionDisplay, type IntegrationPermissionGroup, type IntegrationPermissionOption, type IntegrationProvider, type IntegrationSort, type IntegrationTone, type IntegrationsAppRow, type IntegrationsCatalogProps, type IntegrationsCatalogRow, type IntegrationsPanelProps, type IntegrationsProviderRow, OAuthConnectionParameterDialog as OAuthConnectionParameterModal, type OAuthConnectionParameterDialogProps, type ProviderIconProps, type UseIntegrationsOptions, type UseIntegrationsResult };