Function addSpec

packages/plugins/openapi/src/sdk/plugin.ts:699–854

(config: OpenApiSpecConfig)

        });

      const addSpec = (config: OpenApiSpecConfig) =>
        Effect.gen(function* () {
          // Resolve URL → text and parse BEFORE opening a transaction. Holding
          // `BEGIN` across a network fetch is the Hyperdrive deadlock path.
          const resolved = yield* resolveSpecForInput(config, httpClientLayer);
          const compiled = resolved.keepPathItem
            ? undefined
            : yield* compileOpenApiSpec(resolved.specText);
          const adapter = yield* resolveSpecFormatAdapter(
            options?.specFormats ?? [],
            config.specFormat,
          );
          const derivedIdentity =
            adapter?.deriveIdentity && resolved.document
              ? adapter.deriveIdentity(resolved.document)
              : null;
          const resolvedSlug = config.slug?.trim() || derivedIdentity?.slug;
          if (!resolvedSlug) {
            return yield* new OpenApiParseError({
              message: "OpenAPI integration slug is required",
            });
          }

          // Defaults the add page derives from its preview, applied here so
          // headless callers (MCP, API) get the same integration the UI's
          // add flow would produce - see e2e/scenarios/connect-handoff.test.ts:
          //   - effectiveBaseUrl: the spec's first server, used to anchor the
          //     derived auth template's absolute URLs. It is NOT stored as the
          //     connection baseUrl - the request host is resolved per call from
          //     the operation's extracted `servers`.
          //   - authenticationTemplate: the spec's declared security schemes
          //     (else the Add-connection modal is a dead "No authentication"
          //     end with nowhere to paste a credential)
          // An explicit input always wins; for auth, an explicit EMPTY array
          // means "no auth methods" and suppresses the derivation.
          const explicitBaseUrl = config.baseUrl ?? resolved.baseUrl;
          const needsDerivedBaseUrl = explicitBaseUrl == null;
          const needsDerivedAuth = config.authenticationTemplate == null;
          const preview =
            needsDerivedBaseUrl || needsDerivedAuth
              ? yield* previewSpecText(resolved.specText).pipe(
                  Effect.flatMap((rawPreview) =>
                    enrichPreviewWithDiscoveredOAuth({
                      specText: resolved.specText,
                      preview: rawPreview,
                      specUrl: resolved.specUrl ?? specInputToSpecUrl(config.spec),
                      baseUrl: explicitBaseUrl,
                    }),
                  ),
                )
              : undefined;
          const derivedBaseUrl =
            needsDerivedBaseUrl && preview ? firstBaseUrlForPreview(preview) : undefined;
          const effectiveBaseUrl = explicitBaseUrl ?? (derivedBaseUrl || undefined);
          const derivedAuthenticationTemplate =
            needsDerivedAuth && preview
              ? deriveAuthenticationTemplateFromPreview(preview, effectiveBaseUrl)
              : undefined;