@opengeni/react 3.3.2 → 3.4.0

package/src/connect-panel.tsx

@@ -0,0 +1,99 @@
+import { ConnectAccounts } from "./connect-accounts";
+import { ConnectChooser } from "./connect-chooser";
+import { ConnectSetup, type ConnectSetupProps } from "./connect-setup";
+import { useConnect } from "./hooks/use-connect";
+import type { OpenGeniClient } from "@opengeni/sdk";
+import { useState } from "react";
+import { connectionServicePresentation } from "./connection-service-presentation";
+import { ConnectionDiscovery } from "./connection-discovery";
+
+export type ConnectPanelProps = ConnectSetupProps & {
+  returnUrl: string;
+  /** Null omits the heading when the host already supplies one. */
+  title?: string | null;
+  showAccounts?: boolean;
+  /** Presentation only; the host backend owns acquisition admission. */
+  showCustomConnections?: boolean;
+  /** Include ready, non-custom adapters from the host's Connect catalogue. */
+  showProviderConnections?: boolean;
+  presentation?: "select" | "catalog";
+  client?: OpenGeniClient | undefined;
+};
+
+/** Optional composition over the same unstyled surfaces. Import
+ * @opengeni/react/connect.css for styling; the host retains navigation,
+ * transport, actor admission, and controller lifetime. */
+export function ConnectPanel({
+  returnUrl,
+  title = "Connections",
+  showAccounts = true,
+  showCustomConnections = true,
+  showProviderConnections = false,
+  presentation = "select",
+  className,
+  client,
+  ...setup
+}: ConnectPanelProps) {
+  const { attempt } = useConnect(setup.controller);
+  const [inventoryRevision, setInventoryRevision] = useState(0);
+  // Unknown/failed outcomes still need reconciliation or cancellation, not a
+  // competing new acquisition. Unmounting observers never cancels controller work.
+  const activeSetup =
+    attempt !== null && !["complete", "cancelled", "expired"].includes(attempt.state);
+  const serviceName = attempt
+    ? connectionServicePresentation({ id: attempt.providerId, label: "" }).name
+    : "";
+  return (
+    <div className={["og-connect", className].filter(Boolean).join(" ")}>
+      {title !== null && <h2>{title}</h2>}
+      {showAccounts && !activeSetup && (
+        <ConnectAccounts
+          key={inventoryRevision}
+          controller={setup.controller}
+          returnUrl={returnUrl}
+          client={client}
+          onDisconnected={() => setInventoryRevision((value) => value + 1)}
+        />
+      )}
+      {!activeSetup &&
+        (client && presentation === "catalog" ? (
+          <>
+            <ConnectionDiscovery
+              key={inventoryRevision}
+              controller={showProviderConnections ? setup.controller : undefined}
+              client={client}
+              workspaceId={setup.controller.workspaceId}
+              returnUrl={returnUrl}
+              onConfigured={() => setInventoryRevision((value) => value + 1)}
+            />
+            {showCustomConnections && (
+              <details className="og-connect-secondary">
+                <summary>Custom connection</summary>
+                <ConnectChooser
+                  customOnly
+                  presentation={presentation}
+                  controller={setup.controller}
+                  returnUrl={returnUrl}
+                />
+              </details>
+            )}
+          </>
+        ) : (
+          <ConnectChooser
+            presentation={presentation}
+            controller={setup.controller}
+            returnUrl={returnUrl}
+          />
+        ))}
+      {activeSetup && (
+        <ConnectSetup
+          {...setup}
+          authorizeLabel={
+            setup.authorizeLabel ??
+            (serviceName ? `Continue to ${serviceName}` : "Authorize connection")
+          }
+        />
+      )}
+    </div>
+  );
+}

package/src/connect-setup.tsx

@@ -0,0 +1,355 @@
+import { useState, type FormEvent } from "react";
+import type { ConnectAttempt, ConnectController } from "@opengeni/connect";
+import { useConnect } from "./hooks/use-connect";
+
+const setupStatus: Record<ConnectAttempt["state"], string> = {
+  ready: "Ready to connect",
+  requires_user_action: "Authorize your account",
+  credential_input: "Enter connection details",
+  provider_wait: "Waiting for authorization",
+  account_selection: "Choose an account",
+  resource_selection: "Choose resources",
+  preview: "Choose tools",
+  installing: "Adding selected tools…",
+  connected_but_incomplete: "Choose which tools to add",
+  complete: "Connection ready",
+  cancelled: "Setup cancelled",
+  expired: "Setup expired",
+  failed: "Setup could not finish",
+  uncertain: "Setup outcome needs checking",
+};
+
+/** GitHub returned from a non-owner's install request: an organization owner must approve. */
+export function isOwnerApprovalPending(attempt: Pick<ConnectAttempt, "error">): boolean {
+  return attempt.error?.code === "owner_approval_pending";
+}
+
+function deviceVerificationUrl(action: ConnectAttempt["nextAction"]): string | null {
+  if (action.type !== "wait" || !action.verificationUrl) return null;
+  try {
+    const url = new URL(action.verificationUrl);
+    return url.protocol === "https:" && !url.username && !url.password
+      ? action.verificationUrl
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export type ConnectSetupProps = {
+  controller: ConnectController;
+  /** Called synchronously in the click handler so a host can open a popup. */
+  onAuthorize: (attempt: ConnectAttempt) => void | Promise<unknown>;
+  /** Called synchronously on Continue; hosts can reserve a popup before advancing. */
+  onSelectAccount?: (accountId: string) => void | Promise<unknown>;
+  /** Host pagination must retain selections across pages and submit the final set. */
+  onBrowseResources?: (attempt: ConnectAttempt) => void | Promise<unknown>;
+  className?: string;
+  /** Provider-specific label supplied by the embedding host. */
+  authorizeLabel?: string | undefined;
+};
+
+/** Controller-backed setup surface, styled by opt-in connect.css. No provider secrets enter React state. Host owns
+ * chooser, controller lifetime, navigation and recovery after full redirect. */
+export function ConnectSetup(props: ConnectSetupProps) {
+  // Attempt IDs/revisions are not a substitute for actor scope. A host can
+  // recover the same attempt through a replacement controller; never preserve
+  // a previous actor's unsent credential DOM or local errors across that swap.
+  const [scope, setScope] = useState(props.controller);
+  const [generation, setGeneration] = useState(0);
+  if (scope !== props.controller) {
+    setScope(props.controller);
+    setGeneration(generation + 1);
+  }
+  return <ScopedSetup key={generation} {...props} />;
+}
+
+function ScopedSetup({
+  controller,
+  onAuthorize,
+  onBrowseResources,
+  onSelectAccount,
+  className,
+  authorizeLabel = "Authorize connection",
+}: ConnectSetupProps) {
+  const view = useConnect(controller);
+  const [localError, setLocalError] = useState(false);
+  const [navigating, setNavigating] = useState(false);
+  const invoke = (operation: () => unknown | Promise<unknown>) => {
+    setLocalError(false);
+    try {
+      void Promise.resolve(operation()).catch(() => setLocalError(true));
+    } catch {
+      setLocalError(true);
+    }
+  };
+  const attempt = view.attempt;
+  if (!attempt)
+    return (
+      <section
+        className={["og-connect-setup", className].filter(Boolean).join(" ")}
+        aria-label="Connection setup"
+      >
+        <p role="status">Choose a connection to begin.</p>
+      </section>
+    );
+  const action = attempt.nextAction;
+  const verificationUrl = deviceVerificationUrl(action);
+  const terminal = ["complete", "cancelled", "expired"].includes(attempt.state);
+  const awaitingOwner = isOwnerApprovalPending(attempt);
+  const offersGitHubRequest =
+    action.type === "select_account" &&
+    attempt.providerId.startsWith("github") &&
+    action.accounts.some((account) => account.id === "new");
+  const submit = (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const form = event.currentTarget;
+    const data = new FormData(form);
+    if (view.busy || navigating) return;
+    const key = crypto.randomUUID();
+    if (action.type === "credentials") {
+      const values = Object.fromEntries(
+        action.fields.map((field, i) => [field.name, String(data.get(`field-${i}`) ?? "")]),
+      );
+      // Clear the DOM before awaiting remote work; controller never retains values.
+      form.reset();
+      invoke(() => view.advance({ type: "credentials", values }, key));
+    } else if (action.type === "select_account") {
+      const accountId = String(data.get("account") ?? "");
+      if (
+        action.accounts.some((account) => account.id === accountId && account.status !== "disabled")
+      )
+        invoke(async () => {
+          if (!onSelectAccount) return view.advance({ type: "account", accountId }, key);
+          setNavigating(true);
+          try {
+            await onSelectAccount(accountId);
+          } finally {
+            setNavigating(false);
+          }
+        });
+    } else if (action.type === "select_resources") {
+      if (action.cursor) return;
+      const resourceIds = data.getAll("resource").map(String);
+      invoke(() => view.advance({ type: "resources", resourceIds }, key));
+    } else if (action.type === "preview") {
+      const operationIds = data.getAll("operation").map(String);
+      invoke(() =>
+        view.advance(
+          {
+            type: "install",
+            previewId: action.previewId,
+            contentHash: action.contentHash,
+            operationIds,
+          },
+          key,
+        ),
+      );
+    }
+  };
+  return (
+    <section
+      className={["og-connect-setup", className].filter(Boolean).join(" ")}
+      aria-label="Connection setup"
+      aria-busy={view.busy || navigating}
+    >
+      <div className="og-connect-setup-summary">
+        <p className="og-connect-setup-scope">
+          {attempt.ownership === "personal" ? "Personal connection" : "Workspace connection"}
+        </p>
+        <p role="status" className="og-connect-setup-status">
+          {awaitingOwner
+            ? "Waiting for an organization owner"
+            : attempt.mcpSetup && attempt.state === "credential_input"
+              ? "Enter the requested key"
+              : setupStatus[attempt.state]}
+        </p>
+        <p className="og-connect-setup-description">
+          {attempt.ownership === "personal"
+            ? "Only your work can use this connection."
+            : "Work in this workspace can use this connection."}
+        </p>
+      </div>
+      {attempt.account && <p>Account: {attempt.account.label}</p>}
+      {awaitingOwner && (
+        <div className="og-connect-setup-pending">
+          <p>
+            Your request was sent. GitHub asked the owners of your organization to approve Opengeni.
+          </p>
+          <ol>
+            <li>An organization owner approves the request on GitHub.</li>
+            <li>
+              An owner then connects the organization here. If they don't use Opengeni yet, invite
+              them to this workspace first.
+            </li>
+          </ol>
+          <p>Nothing is connected until then. You can close this and keep working.</p>
+        </div>
+      )}
+      {(localError || view.error || (attempt.error && !awaitingOwner)) && (
+        <p role="alert">
+          {attempt.error?.code === "source_changed"
+            ? "The integration source changed. Review the updated tools before adding them."
+            : attempt.error?.code === "mcp_verification_failed"
+              ? "Could not verify this connection. Check the key and server, then submit again. Nothing was connected."
+              : "Connection setup could not continue. Refresh its status before trying again."}
+        </p>
+      )}
+      {!terminal && (
+        <form key={`${attempt.id}:${attempt.revision}`} onSubmit={submit} autoComplete="off">
+          <fieldset disabled={view.busy || navigating}>
+            {["credentials", "select_account", "select_resources", "preview"].includes(
+              action.type,
+            ) ? (
+              <legend className={attempt.mcpSetup ? "og-capability-catalog-sr-only" : undefined}>
+                Connection details
+              </legend>
+            ) : null}
+            {attempt.state === "connected_but_incomplete" &&
+              action.type === "none" &&
+              !awaitingOwner && (
+                <button
+                  type="button"
+                  className="og-connect-setup-primary"
+                  onClick={() => invoke(() => view.advance({ type: "retry" }, crypto.randomUUID()))}
+                >
+                  Choose tools
+                </button>
+              )}
+            {action.type === "credentials" &&
+              action.fields.map((field, i) => (
+                <label key={field.name}>
+                  {field.label}
+                  {field.options ? (
+                    <select name={`field-${i}`} required={field.required} defaultValue="">
+                      <option value="">
+                        {field.required ? "Choose an option" : "No account (public service)"}
+                      </option>
+                      {field.options.map((option) => (
+                        <option key={option.value} value={option.value}>
+                          {option.label}
+                        </option>
+                      ))}
+                    </select>
+                  ) : (
+                    <input
+                      name={`field-${i}`}
+                      type={field.secret ? "password" : "text"}
+                      required={field.required}
+                      autoComplete="off"
+                    />
+                  )}
+                </label>
+              ))}
+            {action.type === "select_account" && (
+              <label>
+                Account
+                <select name="account" required defaultValue="">
+                  <option value="" disabled>
+                    Choose an account
+                  </option>
+                  {action.accounts.map((account) => (
+                    <option
+                      key={account.id}
+                      value={account.id}
+                      disabled={account.status === "disabled"}
+                    >
+                      {account.label} — {account.id} ({account.ownership})
+                    </option>
+                  ))}
+                </select>
+              </label>
+            )}
+            {offersGitHubRequest && (
+              <p className="og-connect-setup-hint">
+                Don't see your organization? Only its owners can connect it. Choose "Install on
+                another GitHub account" and pick the organization: GitHub lets you send its owners a
+                request to approve.
+              </p>
+            )}
+            {action.type === "select_resources" &&
+              action.resources.map((resource) => (
+                <label key={resource.id}>
+                  <input type="checkbox" name="resource" value={resource.id} />
+                  {resource.label} ({resource.kind})
+                </label>
+              ))}
+            {action.type === "select_resources" && action.cursor && (
+              <>
+                <p>More resources are available. Review all pages before submitting a selection.</p>
+                {onBrowseResources && (
+                  <button
+                    type="button"
+                    onClick={() => invoke(() => onBrowseResources(structuredClone(attempt)))}
+                  >
+                    Browse all resources
+                  </button>
+                )}
+              </>
+            )}
+            {action.type === "preview" && (
+              <>
+                <p>Choose the tools agents can use with this account.</p>
+                {action.operations.map((operation) => (
+                  <label key={operation.id}>
+                    <input type="checkbox" name="operation" value={operation.id} />
+                    {operation.label} ({operation.kind})
+                  </label>
+                ))}
+              </>
+            )}
+            {["credentials", "select_account", "select_resources", "preview"].includes(
+              action.type,
+            ) && (
+              <button
+                type="submit"
+                className="og-connect-setup-primary"
+                disabled={action.type === "select_resources" && Boolean(action.cursor)}
+              >
+                {action.type === "preview"
+                  ? "Add selected tools"
+                  : attempt.mcpSetup && action.type === "credentials"
+                    ? view.busy
+                      ? "Verifying connection…"
+                      : "Connect"
+                    : "Continue"}
+              </button>
+            )}
+            {action.type === "authorize" && (
+              <button
+                type="button"
+                className="og-connect-setup-primary"
+                onClick={() => invoke(() => onAuthorize(structuredClone(attempt)))}
+              >
+                {navigating ? "Waiting for authorization…" : authorizeLabel}
+              </button>
+            )}
+            {action.type === "wait" && (
+              <>
+                {action.userCode && (
+                  <p>
+                    Verification code: <code>{action.userCode}</code>
+                  </p>
+                )}
+                <p>Complete provider authorization, then check the connection status.</p>
+                {verificationUrl && (
+                  <a href={verificationUrl} target="_blank" rel="noopener noreferrer">
+                    Open provider verification page (new tab)
+                  </a>
+                )}
+              </>
+            )}
+            <div className="og-connect-setup-secondary">
+              <button type="button" onClick={() => invoke(() => view.refresh())}>
+                Check status
+              </button>
+              <button type="button" onClick={() => invoke(() => view.cancel(crypto.randomUUID()))}>
+                Cancel setup
+              </button>
+            </div>
+          </fieldset>
+        </form>
+      )}
+    </section>
+  );
+}

package/src/connect.ts

@@ -0,0 +1,60 @@
+// Optional, unstyled React adapter over the shared headless controller.
+// The host owns controller lifetime; unmounting one observer does not cancel an
+// attempt another observer is displaying or a durable backend operation.
+export { useConnect } from "./hooks/use-connect";
+export {
+  CapabilityCatalogRow,
+  CapabilityCatalogIndicator,
+  type CapabilityCatalogRowProps,
+  type CapabilityCatalogStatus,
+} from "./capability-catalog-row";
+export {
+  SkillDiscovery,
+  type SkillDiscoveryProps,
+  type SkillDiscoveryClient,
+  type SkillDiscoveryItem,
+  type SkillDiscoveryPage,
+} from "./skill-discovery";
+export { ConnectSetup, isOwnerApprovalPending, type ConnectSetupProps } from "./connect-setup";
+export { ConnectChooser, type ConnectChooserProps } from "./connect-chooser";
+export { ConnectAccounts, type ConnectAccountsProps } from "./connect-accounts";
+export { ConnectPanel, type ConnectPanelProps } from "./connect-panel";
+export { ConnectionDiscovery, type ConnectionDiscoveryProps } from "./connection-discovery";
+export {
+  McpConnectionCard,
+  type McpConnectionCardProps,
+} from "./components/session-mcp-capability-card";
+export { DeviceAuthorization, type DeviceAuthorizationProps } from "./device-authorization";
+export {
+  IdentityLinkConsent,
+  type IdentityLinkClient,
+  type IdentityLinkConsentProps,
+} from "./identity-link-consent";
+export { IdentityLinkAccounts, type IdentityLinkAccountsClient } from "./identity-link-accounts";
+
+export type { ConnectSnapshot } from "@opengeni/connect";
+export type {
+  ConnectAccount,
+  ConnectAdvance,
+  ConnectAttempt,
+  ConnectNextAction,
+  ConnectOwnership,
+  ConnectProvider,
+  ConnectResource,
+  ConnectTransport,
+} from "@opengeni/connect";
+
+export {
+  ConnectionCatalog,
+  ConnectionServiceRow,
+  ConnectionOptionRow,
+  type ConnectionCatalogProps,
+  type ConnectionCatalogService,
+  type ConnectionCatalogOption,
+} from "./connection-catalog";
+export { ConnectionInstalled, type ConnectionInstalledItem } from "./connection-installed";
+export { ConnectionTypePicker, type ConnectionType } from "./connection-type-picker";
+export { ConnectionLogo } from "./connection-logo";
+export { capabilityLogoFallback } from "./capability-logo-fallback";
+export { PluginDiscovery, type PluginDiscoveryProps } from "./plugin-discovery";
+export { PluginDetails } from "./plugin-details";

package/src/connection-assets.d.ts

@@ -0,0 +1,4 @@
+declare module "*.ico" {
+  const source: string;
+  export default source;
+}

package/src/connection-catalog.tsx

@@ -0,0 +1,162 @@
+import type { ReactNode } from "react";
+import {
+  CapabilityCatalogIndicator,
+  CapabilityCatalogRow,
+  type CapabilityCatalogStatus,
+} from "./capability-catalog-row";
+
+/** Status comes from the host/controller, never inferred from a display label. */
+export type ConnectionCatalogOption = {
+  id: string;
+  name: string;
+  description?: string | undefined;
+  status: string;
+  connected: boolean;
+  /** Explicit health/availability. Omit to retain visible legacy status text. */
+  state?: CapabilityCatalogStatus;
+  onOpen: () => void;
+  action?: ReactNode;
+};
+export type ConnectionCatalogService = {
+  id: string;
+  name: string;
+  logo?: ReactNode;
+  options: ConnectionCatalogOption[];
+};
+export type ConnectionCatalogProps = {
+  services: ConnectionCatalogService[];
+  query?: string;
+  columns?: 1 | 2;
+  resultLimit?: number;
+  onShowMore?: () => void;
+  /** Group capabilities by service, or show every capability independently. */
+  grouped?: boolean;
+  className?: string;
+  emptyMessage?: string;
+};
+
+export function ConnectionOptionRow({ option }: { option: ConnectionCatalogOption }) {
+  return (
+    <div className="og-connection-catalog-action-row og-connection-option">
+      <CapabilityCatalogRow
+        name={option.name}
+        description={option.description}
+        status={option.state ?? (option.connected ? "added" : "available")}
+        statusLabel={option.status}
+        showStatusLabel={option.state === undefined}
+        onOpen={option.onOpen}
+      />
+      {option.action ? <span className="og-connection-option-action">{option.action}</span> : null}
+    </div>
+  );
+}
+
+export function ConnectionServiceRow({ service }: { service: ConnectionCatalogService }) {
+  if (!service.options.length) return null;
+  const connected = service.options.filter((option) => option.connected).length;
+  const attention = service.options.find(
+    (option) => option.state === "attention" || option.state === "unavailable",
+  );
+  const groupState =
+    attention?.state ??
+    (service.options.some((option) => option.state === "loading")
+      ? "loading"
+      : connected === service.options.length
+        ? "added"
+        : "available");
+  const identity = (
+    <>
+      <span className="og-capability-catalog-icon">{service.logo}</span>
+      <span className="og-capability-catalog-copy">
+        <strong>{service.name}</strong>
+        <span>
+          {service.options.length === 1
+            ? service.options[0]?.description
+            : service.options.map((option) => option.name).join(" · ")}
+        </span>
+      </span>
+      <CapabilityCatalogIndicator
+        status={groupState}
+        label={attention?.status ?? `${connected} of ${service.options.length} added`}
+      />
+    </>
+  );
+  return service.options.length === 1 ? (
+    <div className="og-connection-catalog-action-row">
+      <CapabilityCatalogRow
+        name={service.name}
+        description={service.options[0]!.description}
+        icon={service.logo}
+        status={service.options[0]!.state ?? (connected ? "added" : "available")}
+        statusLabel={service.options[0]!.status}
+        showStatusLabel={service.options[0]!.state === undefined}
+        onOpen={service.options[0]!.onOpen}
+      />
+      {service.options[0]?.action}
+    </div>
+  ) : (
+    <details className="og-connection-catalog-service">
+      <summary className="og-capability-catalog-row">
+        {identity}
+        <span aria-hidden className="og-connection-group-chevron">
+          ⌄
+        </span>
+      </summary>
+      <div className="og-connection-catalog-options">
+        {service.options.map((option) => (
+          <ConnectionOptionRow key={option.id} option={option} />
+        ))}
+      </div>
+    </details>
+  );
+}
+
+export function ConnectionCatalog({
+  services,
+  query = "",
+  columns = 1,
+  grouped = true,
+  resultLimit,
+  onShowMore,
+  className = "",
+  emptyMessage = "No connections match your search.",
+}: ConnectionCatalogProps) {
+  const search = query.trim().toLowerCase();
+  const entries = grouped
+    ? services
+    : services.flatMap((service) =>
+        service.options.map((option) => ({
+          ...service,
+          id: `${service.id}/${option.id}`,
+          name:
+            service.options.length > 1 && option.name !== service.name
+              ? `${service.name} · ${option.name}`
+              : service.name,
+          options: [option],
+        })),
+      );
+  const visible = entries.filter((service) =>
+    [service.name, ...service.options.flatMap((option) => [option.name, option.description ?? ""])]
+      .join(" ")
+      .toLowerCase()
+      .includes(search),
+  );
+  return (
+    <>
+      <div className={`og-connection-catalog ${className}`} data-columns={columns}>
+        {visible.length ? (
+          visible
+            .slice(0, resultLimit)
+            .map((service) => <ConnectionServiceRow key={service.id} service={service} />)
+        ) : (
+          <p role="status">{emptyMessage}</p>
+        )}
+      </div>
+      {resultLimit && visible.length > resultLimit ? (
+        <button className="og-catalog-more" type="button" onClick={onShowMore}>
+          View all connections
+        </button>
+      ) : null}
+    </>
+  );
+}