Provider failure classification: reviewer evidence

export function classifyProviderFailure(
  provider: PaymentProvider,
  error: unknown,
): ProviderFailureKind {
  switch (provider) {
    case "stripe":
      return classifyStripeFailure(error);
    case "square": {
      if (typeof error !== "object" || error === null) return "local";
      const name = "name" in error ? error.name : undefined;
      if (name === "SquareTimeoutError") return "transient";

      const statusCode = "statusCode" in error ? error.statusCode : undefined;
      const errors = "errors" in error ? error.errors : undefined;
      const hasSquareResponseErrors =
        Array.isArray(errors) &&
        errors.some(
          (entry) =>
            typeof entry === "object" &&
            entry !== null &&
            ("code" in entry || "category" in entry),
        );
      // Fern wraps a non-timeout, non-status transport failure in SquareError
      // with the SDK's exact fallback error pair and an optional cause.
      const hasUnknownTransportFallback =
        typeof statusCode !== "number" &&
        Array.isArray(errors) &&
        errors.some(
          (entry) =>
            typeof entry === "object" &&
            entry !== null &&
            "category" in entry &&
            entry.category === "V1_ERROR" &&
            "code" in entry &&
            entry.code === "Unknown",
        );
      if (hasUnknownTransportFallback) return "transient";
      return typeof statusCode === "number" || hasSquareResponseErrors
        ? "rejection"
        : "local";
    }
  }

  // A local process or configuration failure is not connection health. Keep
  // the merchant row and its last verified snapshot untouched, but raise it to
  // platform operators instead of suggesting that the studio reconnect.
  const internalFaults = readiness.blockers.filter(
    (blocker) => blocker.code === "internal",
  );
  if (internalFaults.length > 0) {
    logger.error(
      "Payment connection health check failed inside this deployment",
      {
        job: JOB_NAME,
        brandId: brand.id,
        provider: connection.provider,
        blockers: internalFaults.map((fault) => fault.message),
      },
    );
    if (faults.length === 0) return;
  }

  const recorded = await recordConnectionHealth(db, {
    connectionId: connection.id,
    brandId: connection.brandId,
    provider: connection.provider,
    lastError:
      faults.length === 0
        ? null
        : faults.map((fault) => HEALTH_FAULT_MESSAGES[fault.code]).join(" "),
    // Overwritten whenever the provider answered: a snapshot of a failing
    // account is the thing whoever triages this needs, and leaving the
    // activation-era one in place is precisely the misdirection #1542 is
    // about. Omitted when the check never got far enough to build one (a
    // credential the provider refuses outright), because the stored snapshot
    // is then stale but true, and dropping it would also drop the
    // `providerCurrency` that holds the brand's currency read-only while this
    // connection is live.
    ...(readiness.check && internalFaults.length === 0
      ? { activationCheck: readiness.check }
      : {}),
    verifiedIdentity: connection,
  });

  if (kind === "local") {
    const span = trace.getActiveSpan();
    span?.setStatus({ code: SpanStatusCode.ERROR });
    recordSanitizedException(span, params.error);
  }

  if (kind === "credential" && params.connectionId) {
    const label = params.provider === "stripe" ? "Stripe" : "Square";
    await recordConnectionHealth(db, {
      connectionId: params.connectionId,
      brandId: params.brandId,
      provider: params.provider,
      lastError: `${label} refused these credentials while ${params.operation}. Reconnect ${label} in Settings. [ref: ${errorId}]`,
      onlyIfUnmarkedSince: params.resolvedAt,
    });
  }