@ethisyscore/plugin-ui 1.93.0 → 1.95.0

package/dist/connector-mappings/index.js

@@ -0,0 +1,1020 @@
+import { useQueryClient, useMutation, useQuery } from '@tanstack/react-query';
+import { useState, useRef, useEffect, useMemo, useCallback } from 'react';
+
+// src/connector-mappings/ConnectorMappingService.ts
+function pluginTargetSurfaceUnavailable(method, detail) {
+  throw new Error(
+    `ConnectorMappingService.${method} is not available. ${detail} Subclass this service with your own implementation, or leave the plugin-target surface unmounted (isPluginTargetSurfaceAvailable is false on this implementation).`
+  );
+}
+var ConnectorMappingService = class {
+  constructor(invoker) {
+    this.invoker = invoker;
+  }
+  invoker;
+  /** Single seam every method goes through, so a subclass can wrap logging or retries in one place. */
+  async tool(name, args = {}) {
+    return await this.invoker(name, args);
+  }
+  async getMappings(connectorId, moduleKey) {
+    const response = await this.tool("connectors:mappings:list", {
+      connectorId,
+      moduleKey
+    });
+    return response?.items ?? [];
+  }
+  async updateMapping(connectorId, moduleKey, operationKey, toolName, rowVersion, requestFieldMap, responseFieldPaths, staticRequestFields) {
+    const response = await this.tool("connectors:mappings:set", {
+      connectorId,
+      moduleKey,
+      operationKey,
+      toolName,
+      rowVersion,
+      // Coalesced to explicit nulls rather than left `undefined`. The host treats both the same
+      // way, but an explicit null states on the wire that the caller MEANT no override, which is
+      // what makes a request log readable when a translation goes missing.
+      requestFieldMap: requestFieldMap ?? null,
+      responseFieldPaths: responseFieldPaths ?? null,
+      staticRequestFields: staticRequestFields ?? null
+    });
+    return response?.rowVersion ?? null;
+  }
+  async deleteMapping(connectorId, moduleKey, operationKey, rowVersion) {
+    await this.tool("connectors:mappings:delete", {
+      connectorId,
+      moduleKey,
+      operationKey,
+      rowVersion
+    });
+  }
+  async autoMatch(connectorId, moduleKey) {
+    const response = await this.tool(
+      "connectors:mappings:auto-match",
+      { connectorId, moduleKey }
+    );
+    return {
+      items: response?.items ?? [],
+      aiAvailable: response?.aiAvailable ?? false,
+      aiUnavailableReason: response?.aiUnavailableReason ?? null,
+      unmatchedRequiredCount: response?.unmatchedRequiredCount ?? 0,
+      conflictReason: response?.conflictReason ?? null
+    };
+  }
+  async getMappingCompleteness(connectorId, moduleKey) {
+    const response = await this.tool(
+      "connectors:mappings:completeness",
+      { connectorId, moduleKey }
+    );
+    return response ?? { operations: [] };
+  }
+  async suggestMappingTranslation(connectorId, moduleKey, body) {
+    const response = await this.tool(
+      "connectors:mappings:suggest-translation",
+      {
+        connectorId,
+        moduleKey,
+        operationKey: body.operationKey,
+        toolName: body.toolName,
+        // The host declares SampleArgs non-nullable; an absent sample is an empty object, not null.
+        sampleArgs: body.sampleArgs ?? {}
+      }
+    );
+    return response ?? {
+      success: false,
+      error: "The host returned no suggestion.",
+      // Empty objects, not null: the contract types these as `Record<string, string>`, and an
+      // empty map is the accurate statement — no rewrites proposed.
+      requestFieldMap: {},
+      responseFieldPaths: {}
+    };
+  }
+  async testMapping(connectorId, moduleKey, body) {
+    const response = await this.tool("connectors:mappings:test", {
+      connectorId,
+      moduleKey,
+      operationKey: body.operationKey,
+      toolName: body.toolName,
+      requestFieldMap: body.requestFieldMap,
+      responseFieldPaths: body.responseFieldPaths,
+      staticRequestFields: body.staticRequestFields,
+      sampleArgs: body.sampleArgs
+    });
+    return response ?? {
+      success: false,
+      error: "The host returned no result for the mapping test.",
+      rawResponseJson: null,
+      extractedFields: []
+    };
+  }
+  // -------------------------------------------------------------------------
+  // IConnectorEnumerationService — optional, see the interface's remarks
+  // -------------------------------------------------------------------------
+  async listConnectors() {
+    const response = await this.tool(
+      "settings:list-connectors",
+      {}
+    );
+    return (response?.items ?? []).map((c) => ({
+      id: c.id,
+      name: c.name,
+      slug: c.slug ?? null,
+      isEnabled: c.isEnabled
+    }));
+  }
+  async getModuleProvider(moduleKey) {
+    const response = await this.tool("connectors:mappings:get-provider", {
+      moduleKey
+    });
+    return {
+      targetKind: response?.targetKind ?? null,
+      connectorId: response?.connectorId ?? null,
+      targetExtensionId: response?.targetExtensionId ?? null,
+      rowVersion: response?.rowVersion ?? null
+    };
+  }
+  async setModuleProvider(moduleKey, targetKind, connectorId, targetExtensionId, rowVersion) {
+    const response = await this.tool("connectors:mappings:set-provider", {
+      moduleKey,
+      targetKind,
+      connectorId,
+      targetExtensionId,
+      rowVersion
+    });
+    return {
+      targetKind: response?.targetKind ?? targetKind,
+      connectorId: response?.connectorId ?? null,
+      targetExtensionId: response?.targetExtensionId ?? null,
+      rowVersion: response?.rowVersion ?? null
+    };
+  }
+  async listConnectorTools(connectorId) {
+    const response = await this.tool(
+      "settings:get-connector",
+      { id: connectorId }
+    );
+    return response?.tools ?? [];
+  }
+  // -------------------------------------------------------------------------
+  // The PLUGIN-TARGET surface - declared, and deliberately not reachable yet
+  //
+  // The per-module PROVIDER choice above is reachable: CoreConnect-Api #1329 added
+  // `connectors:mappings:get-provider` and `connectors:mappings:set-provider`, so an operator can
+  // record that a module is served by an installed app. What they still cannot do from a plugin UI
+  // is everything BELOW that choice:
+  //
+  // - the candidate list has no endpoint in ANY transport, so who is on offer has to be supplied to
+  //   this package rather than fetched by it;
+  // - `connectors:mappings:list` takes a connectorId and its rows carry no TargetKind or
+  //   TargetExtensionId, so there is no connector-less read for a plugin-served module;
+  // - `SetPluginTargetMapping` exists as a REST route only
+  //   (`PUT /api/v1/connectors/modules/{moduleKey}/operations/{operationKey}/plugin-target`), and a
+  //   plugin's UI reaches the host over MCP, so the per-operation plugin-target write cannot be
+  //   called from here.
+  //
+  // Implemented as refusals rather than omitted so the shape a real transport must satisfy is
+  // written down in one place, and so the gap is a message an operator's log can carry rather than
+  // a method that silently is not there. `isPluginTargetSurfaceAvailable` is the flag a caller
+  // reads; none of the methods below is called while it is false.
+  // -------------------------------------------------------------------------
+  /**
+   * Whether this transport can serve the plugin-target methods below. `false` here, and the three
+   * methods throw, for the reasons in the block comment above.
+   *
+   * A property and not a guess: "the method exists" and "the method works" are different facts, and
+   * a caller that probed by calling and catching would turn a known gap into a request, an error
+   * toast and a support ticket.
+   */
+  isPluginTargetSurfaceAvailable = false;
+  async listPluginProviders(moduleKey) {
+    pluginTargetSurfaceUnavailable(
+      "listPluginProviders",
+      "The host exposes no candidate listing in any transport. Its routable-tool listing is documented as unsafe to show an end user verbatim because it applies no caller-permission filter, and the write path additionally refuses any tool the consuming application did not declare in its manifest - so the candidate set is a server-side decision, not a client-side filter of a broader list."
+    );
+  }
+  async getPluginTargetMappings(moduleKey) {
+    pluginTargetSurfaceUnavailable(
+      "getPluginTargetMappings",
+      "The host's mapping list read is scoped BY connector (connectors:mappings:list takes a connectorId) and its rows carry no TargetKind or TargetExtensionId, so a plugin-target row has neither a connector to scope it by nor a way to be recognised in the result. No connector-less list exists."
+    );
+  }
+  async setPluginTargetMapping(moduleKey, args) {
+    pluginTargetSurfaceUnavailable(
+      "setPluginTargetMapping",
+      "The host serves PUT /api/v1/connectors/modules/{moduleKey}/operations/{operationKey}/plugin-target over REST only; there is no connectors:mappings:* tool for it, and a plugin's UI reaches the host over MCP."
+    );
+  }
+};
+var CONNECTOR_MAPPING_TOOLS = [
+  "connectors:mappings:list",
+  "connectors:mappings:set",
+  "connectors:mappings:delete",
+  "connectors:mappings:auto-match",
+  "connectors:mappings:completeness",
+  "connectors:mappings:suggest-translation",
+  "connectors:mappings:test",
+  "connectors:mappings:get-provider",
+  "connectors:mappings:set-provider"
+];
+var CONNECTOR_ENUMERATION_TOOLS = [
+  "settings:list-connectors",
+  "settings:get-connector"
+];
+
+// src/components/connectors/mappingQueryKeys.ts
+var CONNECTOR_MAPPINGS_ROOT = "connector-mappings";
+function connectorMappingsQueryKey(connectorId, moduleKey) {
+  return [CONNECTOR_MAPPINGS_ROOT, connectorId, moduleKey];
+}
+function connectorMappingsRootQueryKey() {
+  return [CONNECTOR_MAPPINGS_ROOT];
+}
+function pluginTargetMappingsQueryKey(moduleKey) {
+  return [CONNECTOR_MAPPINGS_ROOT, "plugin-target", moduleKey];
+}
+function connectorMappingCompletenessQueryKey(connectorId, moduleKey) {
+  return [...connectorMappingsQueryKey(connectorId, moduleKey), "completeness"];
+}
+
+// src/components/connectors/mappingCompleteness.ts
+function hasUnmappedRequiredField(op) {
+  return op.unmappedRequiredCanonicalFields.length > 0;
+}
+function selectIncompleteOperations(operations) {
+  return operations.filter(hasUnmappedRequiredField);
+}
+function selectRequiredIncompleteOperations(operations) {
+  return operations.filter((op) => op.isRequired && hasUnmappedRequiredField(op));
+}
+function selectOptionalIncompleteOperations(operations) {
+  return operations.filter((op) => !op.isRequired && hasUnmappedRequiredField(op));
+}
+function selectMappingReadiness(operations) {
+  const required = operations.filter((op) => op.isRequired);
+  const complete = required.filter(
+    (op) => op.isToolMapped && op.unmappedRequiredCanonicalFields.length === 0
+  ).length;
+  return {
+    complete,
+    total: required.length,
+    isReady: required.length > 0 && complete === required.length
+  };
+}
+function useAuthenticatedQuery(options) {
+  const result = useQuery(options);
+  return {
+    ...result,
+    isLoading: result.isLoading,
+    isAuthLoading: false
+  };
+}
+
+// src/connector-mappings/useConnectorMappings.ts
+function useConnectorMappings({
+  service,
+  connectorId,
+  moduleKey
+}) {
+  const query = useAuthenticatedQuery({
+    queryKey: connectorMappingsQueryKey(connectorId, moduleKey),
+    queryFn: () => service.getMappings(connectorId, moduleKey),
+    enabled: !!connectorId && !!moduleKey,
+    meta: { errorTitle: "Error loading tool mappings" }
+  });
+  return {
+    mappings: query.data ?? [],
+    isLoading: query.isLoading,
+    isFetching: query.isFetching,
+    dataUpdatedAt: query.dataUpdatedAt,
+    error: query.error ?? void 0,
+    refetch: () => void query.refetch()
+  };
+}
+function useConnectorMappingCompleteness({
+  service,
+  connectorId,
+  moduleKey
+}) {
+  const query = useAuthenticatedQuery({
+    queryKey: connectorMappingCompletenessQueryKey(connectorId, moduleKey),
+    queryFn: () => service.getMappingCompleteness(connectorId, moduleKey),
+    enabled: !!connectorId && !!moduleKey,
+    meta: { errorTitle: "Error loading mapping completeness" }
+  });
+  const operations = query.data?.operations ?? [];
+  return {
+    operations,
+    readiness: selectMappingReadiness(operations),
+    isLoading: query.isLoading,
+    isFetching: query.isFetching
+  };
+}
+
+// src/components/shared/toast.ts
+function dispatchToast(title, description, variant) {
+  if (typeof window === "undefined" || title.length === 0) {
+    return;
+  }
+  window.dispatchEvent(new CustomEvent("ethisys:toast", { detail: { title, description, variant } }));
+}
+function showSuccessToast(title, description) {
+  dispatchToast(title, description, "success");
+}
+
+// src/connector-mappings/types.ts
+var MAPPING_SOURCE = {
+  keyword: "keyword",
+  ai: "ai",
+  manual: "manual"
+};
+var AI_UNAVAILABLE_REASON = {
+  Timeout: "timeout",
+  ProviderError: "provider_error",
+  ParseError: "parse_error",
+  ContextTooLarge: "context_too_large",
+  NoConnectorConfigured: "no_connector_configured"
+};
+var AUTO_MATCH_CONFLICT_REASON = {
+  AnotherAutoMatchInProgress: "another_auto_match_in_progress"
+};
+var MAPPING_TARGET_KIND = {
+  connector: "connector",
+  plugin: "plugin"
+};
+var MODULE_PROVIDER_KIND = {
+  Connector: "Connector",
+  Plugin: "Plugin"
+};
+var MAPPING_TARGET_KIND_WIRE = {
+  connector: MODULE_PROVIDER_KIND.Connector,
+  plugin: MODULE_PROVIDER_KIND.Plugin
+};
+
+// src/connector-mappings/useConnectorMappingMutations.ts
+function resolveTranslationMember(supplied, stored) {
+  if (supplied !== void 0) return supplied;
+  return stored ?? null;
+}
+function summarise(response) {
+  const items = response?.items ?? [];
+  return {
+    aiAvailable: response?.aiAvailable ?? false,
+    aiUnavailableReason: response?.aiUnavailableReason ?? null,
+    unmatchedRequiredCount: response?.unmatchedRequiredCount ?? 0,
+    matchedByKeyword: items.filter((i) => i.source === MAPPING_SOURCE.keyword).length,
+    matchedByAi: items.filter((i) => i.source === MAPPING_SOURCE.ai).length,
+    conflictReason: response?.conflictReason ?? null
+  };
+}
+function useConnectorMappingMutations({
+  service,
+  connectorId,
+  moduleKey,
+  onMappingSaved,
+  showSuccessToast: showSuccessToast2 = showSuccessToast
+}) {
+  const queryClient = useQueryClient();
+  const [autoMatchSummary, setAutoMatchSummary] = useState(null);
+  const scopeKey = `${connectorId ?? ""}|${moduleKey}`;
+  const summaryScopeRef = useRef(scopeKey);
+  useEffect(() => {
+    if (summaryScopeRef.current === scopeKey) return;
+    summaryScopeRef.current = scopeKey;
+    setAutoMatchSummary(null);
+  }, [scopeKey]);
+  const queryKey = useMemo(
+    () => connectorMappingsQueryKey(connectorId, moduleKey),
+    [connectorId, moduleKey]
+  );
+  const invalidateMappingsAndCompleteness = useCallback(() => {
+    void queryClient.invalidateQueries({ queryKey });
+  }, [queryClient, queryKey]);
+  const autoMatch = useMutation({
+    mutationFn: () => service.autoMatch(connectorId, moduleKey),
+    meta: { errorTitle: "Auto-match failed" },
+    onSuccess: (response) => {
+      setAutoMatchSummary(summarise(response));
+      invalidateMappingsAndCompleteness();
+      const matched = (response?.items ?? []).filter((i) => i.mappedToolName).length;
+      if (connectorId && matched > 0) {
+        onMappingSaved?.(connectorId, moduleKey);
+      }
+      showSuccessToast2("Auto-match complete", `Matched ${matched} operations.`);
+    }
+  });
+  const updateMapping = useMutation({
+    mutationFn: (args) => service.updateMapping(
+      connectorId,
+      moduleKey,
+      args.operationKey,
+      args.toolName,
+      args.rowVersion,
+      args.requestFieldMap,
+      args.responseFieldPaths,
+      args.staticRequestFields
+    ),
+    meta: { errorTitle: "Update failed" },
+    onSuccess: () => {
+      invalidateMappingsAndCompleteness();
+      if (connectorId) {
+        onMappingSaved?.(connectorId, moduleKey);
+      }
+      showSuccessToast2("Mapping updated", "The tool mapping was saved.");
+    }
+  });
+  const deleteMapping = useMutation({
+    mutationFn: (args) => service.deleteMapping(connectorId, moduleKey, args.operationKey, args.rowVersion),
+    meta: { errorTitle: "Remove failed" },
+    onSuccess: () => {
+      invalidateMappingsAndCompleteness();
+      showSuccessToast2("Mapping removed", "The tool mapping was cleared.");
+    }
+  });
+  const triggerAutoMatch = useCallback(() => {
+    if (!connectorId) return;
+    autoMatch.mutate();
+  }, [autoMatch, connectorId]);
+  const updateOrDelete = useCallback(
+    (args, callbacks) => {
+      if (!connectorId) return;
+      if (args.toolName === "") {
+        if (args.rowVersion === "") return;
+        deleteMapping.mutate(
+          { operationKey: args.operationKey, rowVersion: args.rowVersion },
+          callbacks
+        );
+        return;
+      }
+      const rows = queryClient.getQueryData(queryKey) ?? [];
+      const current = rows.find((m) => m.operationKey === args.operationKey);
+      updateMapping.mutate(
+        {
+          ...args,
+          requestFieldMap: resolveTranslationMember(args.requestFieldMap, current?.requestFieldMap),
+          responseFieldPaths: resolveTranslationMember(
+            args.responseFieldPaths,
+            current?.responseFieldPaths
+          ),
+          staticRequestFields: resolveTranslationMember(
+            args.staticRequestFields,
+            current?.staticRequestFields
+          )
+        },
+        callbacks
+      );
+    },
+    [connectorId, updateMapping, deleteMapping, queryClient, queryKey]
+  );
+  return {
+    triggerAutoMatch,
+    isAutoMatching: autoMatch.isPending,
+    updateMapping: updateOrDelete,
+    isUpdating: updateMapping.isPending || deleteMapping.isPending,
+    autoMatchSummary
+  };
+}
+function useSuggestMappingTranslation(service) {
+  return useMutation({
+    mutationFn: async (vars) => {
+      const result = await service.suggestMappingTranslation(
+        vars.connectorId,
+        vars.moduleKey,
+        vars.body
+      );
+      if (!result.success) {
+        throw new Error(
+          result.error ?? "The AI couldn't suggest a translation for this operation."
+        );
+      }
+      return result;
+    },
+    meta: { errorTitle: "Suggest translation failed" }
+  });
+}
+function useTestMapping(service) {
+  return useMutation({
+    mutationFn: (vars) => service.testMapping(vars.connectorId, vars.moduleKey, vars.body),
+    meta: { errorTitle: "Mapping test failed" }
+  });
+}
+function testUnavailable(error) {
+  return { success: false, error, rawResponseJson: null, extractedFields: [] };
+}
+function useMappingTranslationEditor({
+  service,
+  connectorId,
+  moduleKey,
+  mappings,
+  updateMapping
+}) {
+  const [editor, setEditor] = useState(null);
+  const scopeKey = `${connectorId ?? ""}|${moduleKey}`;
+  const editorScopeRef = useRef(scopeKey);
+  useEffect(() => {
+    if (editorScopeRef.current === scopeKey) return;
+    editorScopeRef.current = scopeKey;
+    setEditor(null);
+  }, [scopeKey]);
+  const suggest = useSuggestMappingTranslation(service);
+  const test = useTestMapping(service);
+  const onEditTranslation = useCallback(
+    (operationKey, current) => {
+      setEditor({ operationKey, current });
+    },
+    []
+  );
+  const onCancel = useCallback(() => setEditor(null), []);
+  const onOpenMappingEditor = useCallback(
+    (operation, seed) => {
+      const row = mappings.find((m) => m.operationKey === operation.operationKey);
+      setEditor({
+        operationKey: operation.operationKey,
+        current: seed ?? {
+          requestFieldMap: row?.requestFieldMap ?? null,
+          responseFieldPaths: row?.responseFieldPaths ?? null,
+          staticRequestFields: row?.staticRequestFields ?? null
+        }
+      });
+    },
+    [mappings]
+  );
+  const onSuggestWithAi = useCallback(
+    (operation) => {
+      if (!connectorId) return;
+      const row = mappings.find((m) => m.operationKey === operation.operationKey);
+      suggest.mutate(
+        {
+          connectorId,
+          moduleKey,
+          body: { operationKey: operation.operationKey, toolName: row?.mappedToolName ?? "" }
+        },
+        {
+          onSuccess: (result) => {
+            if (!result.success) return;
+            onOpenMappingEditor(operation, {
+              requestFieldMap: result.requestFieldMap,
+              responseFieldPaths: result.responseFieldPaths,
+              // Preserved, not proposed. See the remarks above.
+              staticRequestFields: row?.staticRequestFields ?? null
+            });
+          }
+        }
+      );
+    },
+    // `moduleKey` is a real dependency, not a module-scope constant: omitting it would capture
+    // whichever module was selected when this callback was created, so a multi-module consumer that
+    // switched module and then asked for a suggestion would get advice on the previous catalogue.
+    [connectorId, moduleKey, mappings, suggest, onOpenMappingEditor]
+  );
+  const onSave = useCallback(
+    (requestFieldMap, responseFieldPaths, staticRequestFields) => {
+      if (!editor) return;
+      const row = mappings.find((m) => m.operationKey === editor.operationKey);
+      if (!row || !row.mappedToolName) {
+        setEditor(null);
+        return;
+      }
+      updateMapping({
+        operationKey: row.operationKey,
+        toolName: row.mappedToolName,
+        rowVersion: row.rowVersion ?? "",
+        // Passed through verbatim, INCLUDING nulls. The editor delivers `null` for a side whose
+        // every input the operator emptied, and that is an explicit "clear this" the fill-in in
+        // `useConnectorMappingMutations` must not overwrite.
+        requestFieldMap,
+        responseFieldPaths,
+        staticRequestFields
+      });
+      setEditor(null);
+    },
+    [editor, mappings, updateMapping]
+  );
+  const onTestMapping = useCallback(
+    async (request) => {
+      if (!editor || !connectorId) {
+        return testUnavailable("No connector or operation selected.");
+      }
+      const row = mappings.find((m) => m.operationKey === editor.operationKey);
+      if (!row?.mappedToolName) {
+        return testUnavailable("No tool mapped to this operation.");
+      }
+      return test.mutateAsync({
+        connectorId,
+        moduleKey,
+        body: {
+          operationKey: editor.operationKey,
+          toolName: row.mappedToolName,
+          requestFieldMap: request.requestFieldMap,
+          responseFieldPaths: request.responseFieldPaths,
+          // The editor's DRAFT static params, not the persisted row's, so the dry-run exercises the
+          // unsaved discriminator the operator is actually testing.
+          staticRequestFields: request.staticRequestFields ?? null,
+          sampleArgs: request.sampleArgs
+        }
+      });
+    },
+    // Same reason as `onSuggestWithAi`: a stale `moduleKey` here would dry-run the edit against a
+    // different catalogue and report the result as if it were this one's.
+    [editor, connectorId, moduleKey, mappings, test]
+  );
+  const editorRow = editor ? mappings.find((m) => m.operationKey === editor.operationKey) : void 0;
+  return {
+    editorRow,
+    isOpen: editor !== null,
+    onEditTranslation,
+    onOpenMappingEditor,
+    onSuggestWithAi,
+    suggestingOperationKey: suggest.isPending ? suggest.variables?.body.operationKey ?? null : null,
+    editorProps: {
+      // Always `true`: the consumer gates the MOUNT on `isOpen`, which is what makes the editor's
+      // lazy state initialisation reseed from the row each time it opens.
+      open: true,
+      operationLabel: editorRow?.label,
+      toolName: editorRow?.mappedToolName,
+      canonicalRequestFields: editorRow?.canonicalRequestFields,
+      canonicalResponseFields: editorRow?.canonicalResponseFields,
+      requestFieldMap: editor?.current.requestFieldMap ?? null,
+      responseFieldPaths: editor?.current.responseFieldPaths ?? null,
+      staticRequestFields: editor?.current.staticRequestFields ?? null,
+      onSave,
+      onCancel,
+      onTestMapping
+    }
+  };
+}
+function useAutoMatchOnConnectorSwitch({
+  connectorId,
+  moduleKey,
+  mappings,
+  isLoading,
+  isAutoMatching,
+  dataUpdatedAt,
+  triggerAutoMatch,
+  initiallySelected = false
+}) {
+  const connectorChangedAtRef = useRef(initiallySelected ? Date.now() : 0);
+  const autoMatchedRef = useRef(null);
+  const scopeKey = `${connectorId ?? ""}|${moduleKey}`;
+  const markConnectorChanged = useCallback(() => {
+    connectorChangedAtRef.current = Date.now();
+  }, []);
+  useEffect(() => {
+    if (!connectorId) return;
+    if (isLoading || isAutoMatching) return;
+    if (dataUpdatedAt <= connectorChangedAtRef.current) return;
+    if (autoMatchedRef.current === scopeKey) return;
+    if (mappings.length > 0 && mappings.some((m) => m.mappedToolName)) return;
+    autoMatchedRef.current = scopeKey;
+    triggerAutoMatch();
+  }, [connectorId, scopeKey, mappings, isLoading, isAutoMatching, dataUpdatedAt, triggerAutoMatch]);
+  return { markConnectorChanged };
+}
+var STORAGE_KEY_PREFIX = "cc-connector-mapping-banner-dismissed";
+function readDismissed(storageKey) {
+  if (!storageKey) return false;
+  try {
+    return localStorage.getItem(storageKey) === "true";
+  } catch {
+    return false;
+  }
+}
+function useMappingBannerDismissal(organisationId, moduleKey) {
+  const storageKey = organisationId ? `${STORAGE_KEY_PREFIX}:${organisationId}:${moduleKey}` : null;
+  const [dismissed, setDismissed] = useState(() => readDismissed(storageKey));
+  const appliedKeyRef = useRef(storageKey);
+  useEffect(() => {
+    if (appliedKeyRef.current === storageKey) return;
+    appliedKeyRef.current = storageKey;
+    setDismissed(readDismissed(storageKey));
+  }, [storageKey]);
+  const dismiss = useCallback(() => {
+    if (!storageKey) return;
+    try {
+      localStorage.setItem(storageKey, "true");
+    } catch {
+    }
+    setDismissed(true);
+  }, [storageKey]);
+  const reset = useCallback(() => {
+    if (!storageKey) return;
+    try {
+      localStorage.removeItem(storageKey);
+    } catch {
+    }
+    setDismissed(false);
+  }, [storageKey]);
+  return { dismissed, dismiss, reset };
+}
+function moduleProviderQueryKey(moduleKey) {
+  return ["connector-mappings", "module-provider", moduleKey];
+}
+var UNCONFIGURED = {
+  targetKind: null,
+  connectorId: null,
+  targetExtensionId: null,
+  rowVersion: null
+};
+function useModuleProvider({
+  service,
+  moduleKey,
+  onProviderChanged
+}) {
+  const queryClient = useQueryClient();
+  const queryKey = useMemo(() => moduleProviderQueryKey(moduleKey), [moduleKey]);
+  const query = useAuthenticatedQuery({
+    queryKey,
+    queryFn: () => service.getModuleProvider(moduleKey),
+    enabled: !!moduleKey,
+    meta: { errorTitle: "Error loading the module's provider" }
+  });
+  const provider = query.data ?? UNCONFIGURED;
+  const save = useMutation({
+    mutationFn: (next) => service.setModuleProvider(
+      moduleKey,
+      next.targetKind,
+      next.connectorId,
+      next.targetExtensionId,
+      provider.rowVersion
+    ),
+    meta: { errorTitle: "Could not change the module's provider" },
+    onSuccess: (stored) => {
+      queryClient.setQueryData(queryKey, stored);
+      onProviderChanged?.(stored);
+    }
+  });
+  const selectConnector = useCallback(
+    (connectorId) => save.mutate({
+      // An empty id is the CLEAR, and it must reach the host as one rather than being dropped
+      // here: leaving the previous selection in place is exactly the "connector is stuck forever"
+      // behaviour this surface has had to fix once already.
+      targetKind: MODULE_PROVIDER_KIND.Connector,
+      connectorId: connectorId || null,
+      targetExtensionId: null
+    }),
+    [save]
+  );
+  const selectExtension = useCallback(
+    (extensionId) => save.mutate({
+      targetKind: MODULE_PROVIDER_KIND.Plugin,
+      connectorId: null,
+      targetExtensionId: extensionId || null
+    }),
+    [save]
+  );
+  return {
+    provider,
+    // Only a CONNECTOR selection produces a connector id. A module served by a plugin has no
+    // connector, and reporting one would make the mapping surface fetch rows for a connector the
+    // operator did not choose.
+    connectorId: provider.targetKind === MODULE_PROVIDER_KIND.Connector ? provider.connectorId ?? "" : "",
+    isLoading: query.isLoading,
+    selectConnector,
+    selectExtension,
+    isSaving: save.isPending,
+    error: query.error ?? save.error ?? void 0
+  };
+}
+
+// src/connector-mappings/targetSelection.ts
+function toWireTargetKind(kind) {
+  return kind === MAPPING_TARGET_KIND.plugin ? MAPPING_TARGET_KIND_WIRE.plugin : MAPPING_TARGET_KIND_WIRE.connector;
+}
+function fromWireTargetKind(value) {
+  if (value === MAPPING_TARGET_KIND_WIRE.connector) return MAPPING_TARGET_KIND.connector;
+  if (value === MAPPING_TARGET_KIND_WIRE.plugin) return MAPPING_TARGET_KIND.plugin;
+  return null;
+}
+function isSameTarget(existing, next) {
+  if (!existing) return false;
+  if (existing.targetKind !== next.kind) return false;
+  if (!existing.mappedToolName) return false;
+  if (existing.mappedToolName !== next.toolName) return false;
+  return next.kind === MAPPING_TARGET_KIND.connector ? existing.connectorId === next.connectorId : existing.targetExtensionId === next.targetExtensionId;
+}
+function buildMappingUpdate({
+  existing,
+  next,
+  translation
+}) {
+  const sameTarget = isSameTarget(existing, next);
+  const decide = (member) => {
+    const supplied = translation?.[member];
+    if (supplied !== void 0) return supplied;
+    if (!sameTarget) return null;
+    return existing?.[member] ?? null;
+  };
+  const update = {
+    targetKind: next.kind,
+    toolName: next.toolName,
+    requestFieldMap: decide("requestFieldMap"),
+    responseFieldPaths: decide("responseFieldPaths"),
+    staticRequestFields: decide("staticRequestFields")
+  };
+  if (next.kind === MAPPING_TARGET_KIND.connector) {
+    update.connectorId = next.connectorId;
+  } else {
+    update.targetExtensionId = next.targetExtensionId;
+  }
+  return update;
+}
+function providerOf(target) {
+  return target.kind === MAPPING_TARGET_KIND.connector ? { kind: MAPPING_TARGET_KIND.connector, connectorId: target.connectorId } : { kind: MAPPING_TARGET_KIND.plugin, targetExtensionId: target.targetExtensionId };
+}
+function providerIdOf(provider) {
+  return provider.kind === MAPPING_TARGET_KIND.connector ? provider.connectorId : provider.targetExtensionId;
+}
+function useConnectorToolMappings({
+  service,
+  connectorId,
+  moduleKey,
+  moduleLabel,
+  connectors,
+  isConnectorsLoading = false,
+  availableTools,
+  onConnectorChange,
+  initiallySelected = false,
+  organisationId,
+  aiProvidersHref,
+  connectorSettingsHref,
+  withHeader,
+  onMappingSaved,
+  showSuccessToast: showSuccessToast2,
+  providerSelectionEnabled = false,
+  pluginProviders,
+  isPluginProvidersLoading = false
+}) {
+  const {
+    provider: storedProvider,
+    connectorId: storedConnectorId,
+    isLoading: isProviderLoading,
+    selectConnector,
+    selectExtension
+  } = useModuleProvider({
+    service,
+    moduleKey: providerSelectionEnabled ? moduleKey : ""
+  });
+  const [pendingKind, setPendingKind] = useState(null);
+  const pendingKindModuleRef = useRef(moduleKey);
+  if (pendingKindModuleRef.current !== moduleKey) {
+    pendingKindModuleRef.current = moduleKey;
+    if (pendingKind !== null) setPendingKind(null);
+  }
+  const storedKind = fromWireTargetKind(storedProvider.targetKind);
+  const providerKind = providerSelectionEnabled ? pendingKind ?? storedKind ?? void 0 : void 0;
+  const isPluginMode = providerKind === MAPPING_TARGET_KIND.plugin;
+  const selectedPluginExtensionId = storedKind === MAPPING_TARGET_KIND.plugin ? storedProvider.targetExtensionId ?? "" : "";
+  const effectiveConnectorId = providerSelectionEnabled ? storedConnectorId : connectorId;
+  const selectedConnectorId = isPluginMode ? void 0 : effectiveConnectorId || void 0;
+  const scope = { service, connectorId: selectedConnectorId, moduleKey };
+  const { mappings, isLoading, dataUpdatedAt } = useConnectorMappings(scope);
+  const { operations: completenessOperations, readiness } = useConnectorMappingCompleteness(scope);
+  const { triggerAutoMatch, isAutoMatching, updateMapping, isUpdating, autoMatchSummary } = useConnectorMappingMutations({ ...scope, onMappingSaved, showSuccessToast: showSuccessToast2 });
+  const editor = useMappingTranslationEditor({
+    service,
+    connectorId: selectedConnectorId,
+    moduleKey,
+    mappings,
+    updateMapping
+  });
+  const { dismissed, dismiss, reset } = useMappingBannerDismissal(organisationId, moduleKey);
+  const { markConnectorChanged } = useAutoMatchOnConnectorSwitch({
+    connectorId: selectedConnectorId,
+    moduleKey,
+    mappings,
+    isLoading,
+    isAutoMatching,
+    dataUpdatedAt,
+    triggerAutoMatch,
+    initiallySelected
+  });
+  const handleProviderKindChange = useCallback(
+    (kind) => {
+      setPendingKind(kind);
+    },
+    []
+  );
+  const handlePluginProviderChange = useCallback(
+    (extensionId) => {
+      selectExtension(extensionId);
+    },
+    [selectExtension]
+  );
+  const handleConnectorChange = useCallback(
+    (id) => {
+      onConnectorChange(id);
+      markConnectorChanged();
+      if (providerSelectionEnabled) selectConnector(id);
+    },
+    // `onConnectorChange` is a real dependency: a consumer that persists per organisation rebinds
+    // its setter once identity resolves, and an empty dep array would capture the pre-identity one
+    // and stop writing through.
+    [onConnectorChange, markConnectorChanged, providerSelectionEnabled, selectConnector]
+  );
+  const handleUpdateMapping = useCallback(
+    (operationKey, toolName, rowVersion) => {
+      if (!selectedConnectorId) return;
+      updateMapping({ operationKey, toolName, rowVersion });
+    },
+    [selectedConnectorId, updateMapping]
+  );
+  const handleAutoMatch = useCallback(() => {
+    if (!selectedConnectorId) return;
+    triggerAutoMatch();
+  }, [selectedConnectorId, triggerAutoMatch]);
+  const previousScopeRef = useRef({
+    connectorId: selectedConnectorId || void 0,
+    moduleKey
+  });
+  useEffect(() => {
+    const previous = previousScopeRef.current;
+    const current = { connectorId: selectedConnectorId || void 0, moduleKey };
+    previousScopeRef.current = current;
+    if (previous.moduleKey !== current.moduleKey) return;
+    if (previous.connectorId === current.connectorId) return;
+    reset();
+  }, [selectedConnectorId, moduleKey, reset]);
+  const effectiveAvailableTools = useMemo(() => {
+    if (!isPluginMode) return availableTools;
+    const chosen = (pluginProviders ?? []).find(
+      (p) => p.extensionId === selectedPluginExtensionId
+    );
+    return (chosen?.tools ?? []).map((t) => ({
+      name: t.toolName,
+      description: t.description ?? ""
+    }));
+  }, [isPluginMode, availableTools, pluginProviders, selectedPluginExtensionId]);
+  const providerOptions = useMemo(
+    () => (pluginProviders ?? []).map((p) => ({ extensionId: p.extensionId, name: p.name })),
+    [pluginProviders]
+  );
+  const surfaceIsLoading = isLoading || isConnectorsLoading || isProviderLoading || isPluginProvidersLoading;
+  return {
+    view: {
+      isLoading: surfaceIsLoading,
+      moduleKey,
+      moduleLabel,
+      withHeader,
+      connectors,
+      selectedConnectorId: selectedConnectorId ?? "",
+      onConnectorChange: handleConnectorChange,
+      // Spread conditionally: for a consumer that has not opted in these keys are ABSENT, not
+      // undefined, so the view's `providerPickerEnabled` check sees exactly what a pre-provider
+      // consumer passes.
+      ...providerSelectionEnabled ? {
+        providerKind,
+        onProviderKindChange: handleProviderKindChange,
+        pluginProviders: providerOptions,
+        selectedPluginExtensionId,
+        onPluginProviderChange: handlePluginProviderChange
+      } : {},
+      mappings,
+      availableTools: effectiveAvailableTools,
+      onUpdateMapping: handleUpdateMapping,
+      onAutoMatch: handleAutoMatch,
+      isUpdating,
+      isAutoMatching,
+      bannerState: dismissed ? null : autoMatchSummary,
+      onDismissBanner: dismiss,
+      aiProvidersHref,
+      connectorSettingsHref,
+      onEditTranslation: editor.onEditTranslation
+    },
+    banner: {
+      operations: completenessOperations,
+      onSuggestWithAi: editor.onSuggestWithAi,
+      onOpenMappingEditor: editor.onOpenMappingEditor,
+      suggestingOperationKey: editor.suggestingOperationKey,
+      // False whenever the consumer has not opted in, not merely when a choice exists. A page with
+      // no provider control on it must not be told it has failed to use one. Also false while the
+      // read is in flight, so the banner does not accuse the operator during a page load.
+      isProviderUnconfigured: providerSelectionEnabled && !isProviderLoading && storedKind === null
+    },
+    editor: editor.editorProps,
+    isEditorOpen: editor.isOpen,
+    editorRow: editor.editorRow,
+    mappings,
+    completenessOperations,
+    readiness,
+    isLoading: surfaceIsLoading
+  };
+}
+
+// src/connector-mappings/connectorOptions.ts
+function mapConnectorsToOptions(connectors) {
+  return connectors.map((c) => ({ id: c.id, name: c.name }));
+}
+function mapConnectorToolsToOptions(tools) {
+  return tools.filter((t) => t.isEnabled).map((t) => ({ name: t.toolName, description: t.description ?? "" }));
+}
+
+// src/components/connectors/providerLabels.ts
+var PROVIDER_CONTROL_LABEL = "Served by";
+var PROVIDER_OPTION_LABEL = {
+  plugin: "This organisation's apps",
+  connector: "External system"
+};
+var PLUGIN_PROVIDER_CONTROL_LABEL = "App";
+var CONNECTOR_CONTROL_LABEL = "Connector";
+
+export { AI_UNAVAILABLE_REASON, AUTO_MATCH_CONFLICT_REASON, CONNECTOR_CONTROL_LABEL, CONNECTOR_ENUMERATION_TOOLS, CONNECTOR_MAPPING_TOOLS, ConnectorMappingService, MAPPING_SOURCE, MAPPING_TARGET_KIND, MAPPING_TARGET_KIND_WIRE, MODULE_PROVIDER_KIND, PLUGIN_PROVIDER_CONTROL_LABEL, PROVIDER_CONTROL_LABEL, PROVIDER_OPTION_LABEL, buildMappingUpdate, connectorMappingCompletenessQueryKey, connectorMappingsQueryKey, connectorMappingsRootQueryKey, fromWireTargetKind, isSameTarget, mapConnectorToolsToOptions, mapConnectorsToOptions, moduleProviderQueryKey, pluginTargetMappingsQueryKey, providerIdOf, providerOf, selectIncompleteOperations, selectMappingReadiness, selectOptionalIncompleteOperations, selectRequiredIncompleteOperations, toWireTargetKind, useAutoMatchOnConnectorSwitch, useConnectorMappingCompleteness, useConnectorMappingMutations, useConnectorMappings, useConnectorToolMappings, useMappingBannerDismissal, useMappingTranslationEditor, useModuleProvider, useSuggestMappingTranslation, useTestMapping };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map